Conventions

Shared behavior across every /api/v1 endpoint — error bodies, status codes, pagination, filters, sorting, dry runs, content types, and publish timing.

Errors

Every failure returns the same body:

{
  "error": {
    "code": "invalid_input",
    "message": "human readable text",
    "params": {},
    "details": {}
  }
}

code is stable and safe to branch on. message is localized from the request locale and may change. details is present when the server can point at a specific field, and often carries path for validation failures.

Common codes and their status:

Code	Status	Meaning
`invalid_input`	400	Body or query failed validation. Check `details.path`.
`unauthorized`	401	Missing or expired token.
`invalid_credentials`	401	Email or password is wrong.
`forbidden`	403	Authenticated, but the role slice denies this action.
`not_found`	404	The resource does not exist or you cannot see it.
`conflict`	409	The write collides with existing state.

Domain-specific codes such as object.field.required, design.block_not_found, or page.not_found keep the same envelope. The full list is in Error codes.

Pagination

List endpoints accept page (1-based) and pageSize. pageSize is capped at 100. Responses that page return the rows plus the total so a client can stop.

Cursor-paged endpoints such as files return cursor instead; pass the previous cursor back to continue.

Filters and sorting

Object entries accept search, filterField/filterOperator/filterValue, or the richer filters array, plus sortBy and sortDirection. Filters are AND-combined. Dotted paths read a field on a related entry.

Operator aliases: equals/eq, not_equals/neq, greater_than/gt, less_than/lt, and gte/lte.

Dry runs

Writes that accept dryRun validate, report what would change, and write nothing. Use it when an agent is unsure: it returns the same errors a real write would, without side effects.

Content types

JSON endpoints expect application/json. File uploads use one of:

multipart/form-data to the files endpoint,
a presigned PUT from create_upload_url followed by complete_upload for large files,
import-url / from-url to pull an existing asset.

Publish timing

Saving a page or chrome writes a revision immediately, but public HTML can serve the previous data-request result until expectedLiveBy, which is about 60 seconds after a save. publishStatus tells you whether a given revision is the one currently served for a path.