# Conventions

Paths, ids, JSON, timestamps, Idempotency-Key, pagination, and how slow changes answer.

Source: https://docs.orbits.africa/api/conventions

## 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 `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.

:::note[Twenty-seven operations take an Idempotency-Key]
- `POST /teams/{team}/notifications`: Mark notifications read.
- `POST /teams/{team}/projects`: Create a project from a repository or a template.
- `POST /teams/{team}/projects/{project}/pause`: Pause or resume a project.
- `POST /teams/{team}/projects/{project}/deployments`: Deploy a branch now.
- `POST /teams/{team}/projects/{project}/uploads`: Start dropping a site or app.
- `POST /teams/{team}/projects/{project}/uploads/{upload}/complete`: Deploy a dropped archive.
- `POST /teams/{team}/projects/{project}/production`: Set what production serves.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/redeploy`: Build the same commit again.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/promote`: Promote to production.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/rollback`: Roll production back.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/cancel`: Cancel a build.
- `POST /teams/{team}/projects/{project}/env`: Add variables, or import a .env file.
- `POST /teams/{team}/projects/{project}/env/{key}/restore`: Undo a delete.
- `POST /teams/{team}/domains`: Add a domain.
- `POST /teams/{team}/domains/{domain}/records`: Add a record.
- `POST /teams/{team}/domains/{domain}/zone-imports`: Import a BIND zone file.
- `POST /teams/{team}/projects/{project}/flags`: Create a flag.
- `POST /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules`: Add a targeting rule.
- `POST /teams/{team}/projects/{project}/workflows/{workflow}/runs`: Run a workflow now.
- `POST /teams/{team}/projects/{project}/workflows/runs/{run}/cancel`: Cancel a running run.
- `POST /teams/{team}/projects/{project}/workflows/runs/{run}/retry`: Retry a failed run from the step that failed.
- `POST /teams/{team}/projects/{project}/sandboxes`: Start a sandbox.
- `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/stop`: Suspend a sandbox.
- `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/start`: Resume a sandbox.
- `POST /teams/{team}/projects/{project}/alerts`: Create an alert rule.
- `POST /teams/{team}/projects/{project}/alerts/preview`: How much traffic a draft rule would see.
- `POST /teams/{team}/alert-channels/webhook/test`: Send a test event to the webhook.
:::

`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`:

```console
$ 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.
