Overview

Responses and errors

Response shape, pagination, protection against overwrites and error codes.

All addresses under /spaces/{space} answer in the same shape. The knowledge base still differs, see below.

Single resource

{
  "data": {
    "id": "0199a3c2-7d4e-7b21-9f3a-2c5e8d1b4a70",
    "name": "Reception",
    "updated_at": "2026-09-21T10:15:00+02:00"
  }
}

Lists

Lists carry meta next to data. Use ?page= to page through and ?per_page= to set the page size (default 50, maximum 200). On the last page next_page is null.

{
  "data": [
    "…"
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 132,
    "next_page": 2
  }
}

Writes

POST, PATCH and DELETE return the resource after the write in data. Resources that have to be published also carry the publish state in sync.

With PATCH, only the fields you send change. Nested objects such as behavior.values or a tool's recipe are merged by key; lists such as tool_ids are replaced as a whole.

Protection against overwrites

Send expected_updated_at with PATCH and DELETE: the updated_at from your last read. If someone else has changed the resource since, the API refuses instead of silently overwriting their change:

{
  "code": "stale",
  "message": "The record changed since you read it.",
  "current": {
    "…": "…"
  }
}

Read current, apply your change to it and send it again.

Errors

Errors always carry code and message. Validation errors also list every invalid field with its path:

{
  "code": "validation",
  "message": "1 field is invalid.",
  "errors": [
    {
      "path": "behavior.values.tone.closeness",
      "code": "invalid_enum",
      "message": "Must be one of formal, personal."
    }
  ]
}

Status	`code`	Meaning
400	`invalid_json`	The body is not valid JSON.
401	`unauthenticated`	Key missing, wrong or deleted.
403	`forbidden`	The key may not do this in this space.
404	`not_found`	The resource does not exist in this space, or the address is wrong.
405	`method_not_allowed`	The address exists, but not with this method.
409	`stale`	`expected_updated_at` no longer matches. `current` holds the current record.
409	`referenced`	Delete refused because something still refers to it. `references` says what.
422	`validation`	Invalid fields. `errors` lists every field with its path.
429	`rate_limited`	More than 60 requests per minute. Respect `Retry-After`.
500	`server_error`	An error on our side. Contact support with the `X-Request-Id`.

Errors from a third party, such as a connected endpoint, are passed through unchanged under code: upstream with the provider's status and message.

Headers

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-Request-Id. The request ID helps support find a call in our logs.

Knowledge base

The addresses under /knowledge are older and still follow the previous shape: lists carry links and meta next to data, errors only message. Every document or folder response contains sync_status and sync_error. Files may be up to 20 MB.