V2
Conventions
Understand pagination, idempotency, concurrency control, rate limits, public routes, and time formats.
Conventions
These conventions apply across the V2 API unless an endpoint page says otherwise.
Pagination
| Field | Direction | Description |
|---|---|---|
start_cursor |
Request | Opaque cursor returned by a previous response. |
page_size |
Request | Requested page size. Defaults to 20; maximum is 100 unless documented otherwise. |
next_cursor |
Response | Cursor for the next page, or null. |
has_more |
Response | Whether another page exists. |
Idempotency-Key
- Write endpoints that support idempotency accept
Idempotency-Key. - Reusing the same key with the same request body returns the same result.
- Reusing the same key with a different body returns
409 idempotency_conflict.
If-Match
- Endpoints that support optimistic concurrency can accept
If-Match. - When the supplied version does not match the current resource version, the API returns
409 conflict. - Use the latest resource version from a read response when available.
Rate Limits
- Rate limited requests return
429 rate_limited. - Responses may include rate-limit headers when available.
- Clients should back off and retry after the indicated delay when provided.
Public Routes
GET /v2/openapi.jsonandGET /v2/openapi/metaare public.- All other V2 routes require a Bearer token.
- Public routes describe the API itself and do not expose private workspace content.
Time Format
Timestamps use ISO 8601 strings, for example 2026-04-09T09:30:00.000Z.
IDs and Cursors
- Resource IDs are strings and are commonly UUIDs.
- Cursors are opaque. Do not parse or construct them manually.
- Use returned cursor values exactly as provided.