OrbitsDocs
esc
    Open Orbits
    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:

    PrefixObject
    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 422 on Idempotency-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:

    Terminal
    $ 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. Poll GET …/deployments/{deployment} every few seconds, or follow GET …/deployments/{deployment}/logs/stream (Server-Sent Events), until its state is ready, failed or canceled.
    • Operations. Other slow changes answer an operation (op_…). Poll GET /v1/operations/{operation} until its state is succeeded or failed; a failed one carries an error.

    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.

    Was this page helpful?

    Updated