Tokens and conventions

Tokens: what each kind may do

Send a token as Authorization: Bearer <token>. Make one under Account → Security; it lives 90 days unless you choose otherwise, at most 365.

A read token reads: GET and HEAD everywhere its person may read, and two requests that change nothing a person sees, queueing an export and signing a preview link. Any other write answers 403 with scope: read.

A write token acts with its person’s role in each team, so an editor’s token cannot do what an editor cannot. It cannot do what a person must do at a screen: stepping up, managing passkeys and recovery codes, signing out other sessions, approving an assistant’s connection, and the operations that ask for step-up (deleting a project or a team, storing a hosting credential, moving a project to another Studio). Those answer 403. Each operation in the reference says which kind it is under x-caller: session-or-token, person or person-stepped-up.

Assistant tokens are a third kind, for AI assistants over the two MCP doors, made with grants instead of a scope. On this API they read as a viewer at most. They are described in Getting started, not here.

From a server, not a browser

The API accepts cross-site browser requests from this Studio’s own dashboard only, so a page on another site cannot call it with a visitor’s browser. Call it from a server, a CI job, a CLI or another service.

Every answer carries x-request-id. Send your own (8 to 64 letters, digits, - or _) to find a request in this Studio’s logs; quote it when you ask for help.

Errors

Every failure is application/problem+json with a code, a detail for people and a request_id. Act on code, not on the HTTP status: two codes share 409 and two share 422.

A body that does not fit is 422 validation_failed with an issues array, one entry per field; there is no 400. A resource you may not see, and an id that is malformed, both answer 404, so that one cannot be told from the other.

Some errors carry more fields, such as reason, scope or limit. Every code and every extra field is on the error codes page.

Paging

Lists are not all paged the same way. Most answer { "data": [...] } with a limit, and a few page further. Each operation in the reference says which it takes; these are the four styles.

Rate limits

There is no general request budget per token. The sign-in and step-up routes and making a team are limited: their answers carry RateLimit-Limit and RateLimit-Remaining, and a refusal is 429 rate_limited with Retry-After in seconds. The reference lists these headers on exactly those operations.

Other limits are on what you make, not how often you ask: projects per team, builds a day, queued jobs, upload size. GET /api/v1/accounts/{team}/usage shows where a team stands, and going over is 409 quota_exceeded with limit, used and max.

Retrying safely: Idempotency-Key

Five operations take an Idempotency-Key header: creating a project, creating a draft, publishing a draft, upgrading a project and exporting one. Send a key of your own, at most 160 characters, to retry without doing the work twice.

A repeat of the same request (method, path and body) with the same key is answered with the first answer and Idempotent-Replay: true. The same key with another request is 409, and so is a repeat while the first is still running, with Retry-After: 5. Keys are kept per team.

Not overwriting somebody else: If-Match

Reading a content entry answers an ETag. Send it back as If-Match when you write the entry, and a write made after somebody else saved it is refused with 412 precondition_failed instead of replacing their work. Read again, apply your change, and write.

What may change

Within /api/v1 every change is additive: operations, optional request fields, response fields and values of a listed field may be added, so a client ignores what it does not know; nothing is removed, renamed or given another meaning, and a change that would break a client is made under a new version prefix and announced in the release notes.

So a client that ignores fields it does not know keeps working, and one that refuses them will break on a release that only added something.

Things that look odd, and stay

They are kept because changing them would break clients that rely on them.