API reference
Every operation in the contract, with its parameters, its responses and a button to try them with your token.
Before you open the reference
This reference is generated from the OpenAPI contract: no endpoint exists unless it is in the contract, and the same document feeds the generated SDKs. Everything hangs off the fixed /api/v1 prefix; changes within v1 are always additive and compatible, and a v2 would ship with an explicit migration plan.
Almost everything hangs off an organization, and its id goes in the path. Operations authenticate with a Personal Access Token as bearer, which an owner or an admin creates in Settings → API keys: it is shown only once. A PAT is issued inside an organization and only reaches that one’s resources; a non-member gets a 404, not a 403.
Every non-2xx response uses the same envelope, and its request_id matches the X-Request-ID header: keep it, because it is what makes a specific request traceable. Validation errors return 422 with code “validation_error”, and on a 429 you should retry with exponential backoff.
- How does a call authenticate?
- With a bearer Personal Access Token in the Authorization header. An owner or an admin of the organization creates it in Settings → API keys; it is shown only once, so copy it then and keep it in a secrets manager.
- Can the operations be tried from here?
- Yes: every operation in the contract has a button to try it with your token. This points at production and whatever you create is real, so start with a test organization if you are going to write.
- How is the API versioned?
- With a fixed prefix, /api/v1. Changes within v1 are always additive and compatible; a v2 would ship with an explicit migration plan.
- What happens when a call fails?
- Read the code in the error envelope and keep the X-Request-ID header, which identifies your specific request. A 401 is a missing, invalid or expired token; a 404, that it does not exist or you are not a member of its organization; and on a 429, retry later with exponential backoff.