Attach or replace an inbox's extraction contract

Endpoint

PUT https://api.dairo.app/v1/inboxes/{inbox}/schema

Attaches or replaces the extraction contract on the inbox. The write is an upsert keyed on the inbox, so a re-PUT replaces the previous contract in full rather than merging into it. schema is a flat map of field name to declaration, where each declaration may set type (string, number, integer, boolean, object, array, url, or email), required, default, maxLength, and enum; a standard JSON Schema with top-level properties and a required array is also accepted and folded into this shape, and the serialized schema is capped at 8192 bytes with unknown types rejected as 400. Setting schema to {} (or omitting it) means no contract, leaving the inbox on plain passthrough delivery. onValidationError defaults to quarantine, which holds a message whose extracted object fails validation out of message.received and emits message.quarantined instead; set passthrough to deliver it anyway with the validation error attached. extractionHint is optional free-text prompt context capped at 1000 characters and never executed — because the write is a full replace, omitting it clears any previous hint; requires the inboxes:write scope.

Scope: inboxes:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X PUT "https://api.dairo.app/v1/inboxes/support/schema" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`inbox`	string	yes	Inbox UUID or full address (e.g. `agent@dairo.app`).

Body

Required, application/json: SetInboxSchemaRequest.

Field	Type	Required	Description
`schema`	InboxSchemaContract	no
`onValidationError`	`"quarantine"`, `"passthrough"`	no	Behaviour when an extracted object fails validation. 'quarantine' (default) holds the message out of message.received and emits message.quarantined; 'passthrough' delivers it with the error attached. (default `"quarantine"`)
`extractionHint`	string or null	no	Optional free-text hint passed to the extractor as prompt context. Never executed. (max length 1000)

Response

200 Success. Body: application/json, InboxSchemaResponse.

Field	Type	Required
`inboxId`	string (uuid)	yes
`schema`	InboxSchemaContract	yes
`onValidationError`	`"quarantine"`, `"passthrough"`	yes
`extractionHint`	string or null	no
`createdAt`	string (date-time)	no
`updatedAt`	string (date-time)	no

200

{
  "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "schema": {},
  "onValidationError": "quarantine",
  "extractionHint": null,
  "createdAt": "2026-10-19T09:30:00Z",
  "updatedAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).