API reference · Using the APIConventions
Conventions
Paths, ids, JSON, timestamps, Idempotency-Key, pagination, and how slow changes answer.
Paths and ids
Every path is under https://api.theorbits.app/v1, and a team's resources are under /v1/teams/{team}/…. Where a path takes {team} you may send the team's slug or its id; {project} is the project's slug or its id; {domain} the domain's name or its id.
Ids carry a prefix that says what they are:
| Prefix | Object |
|---|---|
usr_ | A user |
team_ | A team |
prj_ | A project |
dpl_ | A deployment |
dom_ | A domain |
rec_ | A DNS record |
tok_ | An API token |
op_ | An operation |
Requests and responses
The API speaks JSON. Send bodies with Content-Type: application/json. Timestamps are RFC 3339 in UTC (2026-11-10T09:30:00Z); the dashboard shows them in Lagos time. Numbers are numbers, not formatted strings.
A team you are not a member of, or a resource in it, answers 404, never 403: the API doesn't confirm that something exists to someone who can't see it.
Idempotency-Key
A POST that creates or starts something takes an Idempotency-Key header: a value of 8 to 128 printable characters, new for each change (a UUID is a good choice). If the request fails or times out, send it again with the same key and the same body. The rules:
- The same key with the same request (method, path and body) replays the first successful answer instead of doing the work twice.
- The same key with a different request answers
422onIdempotency-Key, and nothing is applied. - While the first request with a key is still running, a second answers
409. - A request that fails frees its key, so a retry runs it again.
The SDKs and the CLI send a key on every request that takes one, and reuse it when they retry.
PUT, PATCH and DELETE requests don't take the header: sending them twice has the same effect as sending them once. Neither do revealing a variable, pulling variables and checking a domain, which change nothing.
Pagination
Lists take limit (from 1 to 100, 25 by default) and cursor, and answer items and next_cursor. To read everything, send the next_cursor you got as cursor until it is null:
$ curl "https://api.theorbits.app/v1/teams/my-team/projects?limit=100" \ -H "Authorization: Bearer $ORBITS_TOKEN"$ curl "https://api.theorbits.app/v1/teams/my-team/projects?limit=100&cursor=<next_cursor>" \ -H "Authorization: Bearer $ORBITS_TOKEN"A cursor is opaque: don't build or change one. The SDKs have helpers that follow cursors for you.
Slow changes: 202
Anything that takes a while answers 202 as soon as it is recorded: what you asked for is accepted, and the work happens next.
- Deployments. Creating, redeploying or promoting answers the new deployment,
queued. PollGET …/deployments/{deployment}every few seconds, or followGET …/deployments/{deployment}/logs/stream(Server-Sent Events), until itsstateisready,failedorcanceled. - Operations. Other slow changes answer an operation (
op_…). PollGET /v1/operations/{operation}until itsstateissucceededorfailed; a failed one carries anerror.
What is running is reported separately from what was asked for: a deployment's state and its runtime are written by Orbits, never by you.
Planned operations
A few operations in the contract are planned and not served yet. The reference shows them, marked Planned: not available yet, so you can see what is coming; calling one today answers an error. None of the operations in this reference is planned today.