Register an event type

PUT

/event-types/{name}

curl --request PUT \
  --url https://api.sendtruss.com/v1/event-types/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "fields": [ { "name": "example", "type": "string", "required": true, "fallback": "example", "fields": [ { "name": "example", "type": "string", "required": true, "fallback": "example", "fields": "example" } ] } ] }'

• Production

Creates the type (201) or changes its schema (200). A schema only grows, so payloads and templates already bound to it keep working: you can add optional fields, make a required field optional and change a fallback. Removing a field, changing its type, making it required or adding a required field is refused, with each offending field named. Sending the schema it already has changes nothing, so you can register your types on every deploy.

Authorizations

• http

Parameters

Path Parameters

name

required

string

Request Body^required

Media typeapplication/json

object

fields

required

Every field a payload of this type can carry, at most 100. Send the whole schema each time; [] for a type with none.

Array<object>

<= 100 items

object

name

required

Lowercase letters, digits and _, starting with a letter. A template reads it as {{ event.<name> }}.

string

<= 64 characters /^[a-z][a-z0-9_]*$/

type

required

string

Allowed values: string number boolean date datetime money url list

required

required

Whether every payload must carry it: true or false, as JSON booleans.

boolean

fallback

What a template shows when a payload leaves the field out.

string | null

<= 255 characters

fields

The fields of each record in a list, at most 20. Required for a list and refused for any other type.

Array<object>

<= 20 items

object

name

required

string

<= 64 characters /^[a-z][a-z0-9_]*$/

type

required

string

Allowed values: string number boolean date datetime money url

required

required

boolean

fallback

string | null

<= 255 characters

fields

string

Responses

200

Media typeapplication/json

string

Example^generated

example

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

401

The API key is missing, malformed, revoked or expired.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: unauthenticated

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "unauthenticated"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

404

Nothing is at this path for your key. Another platform’s or another workspace’s resource answers the same as one that doesn’t exist.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: not_found

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "not_found"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

409

Refused because of the resource’s current state. The code says why.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: schema_change_not_additive

errors

required

Each field the change would remove or alter, by its path, with what is wrong with it.

object

key

additional properties

Array<string>

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "schema_change_not_additive"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

422

The request is invalid. The code says why, and errors names each field at fault.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: validation_failed

errors

required

Each field that failed validation, by its path in the request, with its messages.

object

key

additional properties

Array<string>

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "validation_failed"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

429

Too many requests. Wait for the seconds in Retry-After.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: rate_limited

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "rate_limited"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

Retry-After

integer

Seconds to wait before trying again.