Requests

• Base URL and version. Paths start with /v1, and almost all of them are scoped to your account: /v1/accounts/<account-id>/…. For the base URL and the Authorization header, see How do I authenticate to the API?
• JSON. Send request bodies as JSON with Content-Type: application/json. A body that isn't valid JSON is refused with 400 BAD_REQUEST ("malformed or unsupported request body").
• Size. A request body can be up to 1 MiB. Workspace imports can be up to 32 MiB. A larger body is refused with 413 PAYLOAD_TOO_LARGE.
• IDs. Objects are identified by opaque IDs. Use them as given; a malformed ID is treated as not found.

A single object

A request that returns one object wraps it in data:

{
  "data": { "id": "…", "name": "Production" }
}

Some responses add a meta object alongside data with extra information about the response. meta is left out when there is nothing to say.

A page of objects

A request that returns a list returns one page at a time:

{
  "data": [ { "id": "…" }, { "id": "…" } ],
  "page": { "limit": 100, "nextCursor": "c1:…" },
  "meta": { "totalMatching": 240 }
}

Paging through a list

Two query parameters control paging:

GET /v1/accounts/<account-id>/workspaces?limit=200
GET /v1/accounts/<account-id>/workspaces?limit=200&cursor=<page.nextCursor>

Keep requesting until page.nextCursor is null. Treat cursors as opaque: don't build or change them. An invalid limit or cursor returns 400 BAD_REQUEST_PAGINATION.

A few list endpoints use a different default or maximum page size; the response's page.limit always tells you what was applied.

Errors

Any response that isn't a success has the same shape:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "workspace not found",
    "status": 404,
    "requestId": "req-1a"
  }
}

Ignore fields you don't recognise: new ones may be added.

Error codes

Rate limits and retries

• The API allows 1,000 requests per 60 seconds per IP address. Over that, it returns 429 RATE_LIMITED with a Retry-After header giving the seconds to wait.
• A sync started too soon also returns 429 RATE_LIMITED, without a Retry-After header; the message says how long to wait ("retry in Ns").
• 429 QUOTA_EXCEEDED doesn't clear by waiting, except for monthly limits at the start of the next month. Free capacity or change plan instead.
• Retry 500 and 503 with a backoff. Don't retry 4xx errors other than 429 without changing the request.

Long-running requests

Requests that start work in the background return 202 Accepted, usually with a Location header that points at the status of that work. See How do I track a long-running request?

Reference

Every endpoint is in the API reference. Open a route there to see its query parameters, its request body and its success response, field by field. The shapes are generated from the server's own types, so they change when the API changes. Files and event streams are listed by media type, and errors always use the error shape above.