# Orbits API: agent brief

You can manage apps hosted on Orbits (projects, deployments, environment variables, domains and DNS, logs, analytics, feature flags, workflows, alerts, usage and billing) through its REST API. This file is the whole contract in brief. Read it before your first call.

Full reference: https://docs.orbits.africa/api
OpenAPI 3.1 contract: https://docs.orbits.africa/openapi/orbits-api.yaml (JSON: https://docs.orbits.africa/openapi/orbits-api.json)
Postman collection: https://docs.orbits.africa/postman/orbits-api.postman_collection.json (also for Insomnia: https://docs.orbits.africa/insomnia/orbits-api.insomnia.json, and Bruno: https://docs.orbits.africa/bruno/orbits-api.bruno.zip)

If your client speaks MCP, connect it to the hosted MCP server instead of calling the API by hand: `https://mcp.theorbits.app/mcp` (guide: https://docs.orbits.africa/ai/connect-your-ai, tools: https://docs.orbits.africa/ai/mcp-tools). If you are writing code, use an SDK: JavaScript `@useorbits/sdk` (npm), Python `useorbits` (PyPI), or Go (https://docs.orbits.africa/sdks). From a terminal, the `orbits` CLI (https://docs.orbits.africa/cli).

## Basics

- Base URL: `https://api.theorbits.app/v1`. Every path below is relative to it. Staging: `https://stagingapi.theorbits.app/v1`.
- Authenticate every request: `Authorization: Bearer $ORBITS_TOKEN`. API tokens start with `orb_live_` and are made by a team's owners and admins in the dashboard (Team › Settings › API tokens). You can't make one through the API.
- A token belongs to one team and acts as the person who made it. Call `GET /me` first: it lists the one team (and, for a project-limited token, the one project) the token reaches.
- `read` tokens may only send `GET` and `HEAD` and never read environment variable values; a write is `403` ("This API token is read-only"). `full` tokens may call everything below.
- A token can never: manage tokens, members or invites, delete the team, change its security rules, move a project to another team, connect or change integrations, or use the sign-in and account routes. Those answer `403`; ask the human to do them in the dashboard.
- `{team}` is a team's slug or `team_` id; `{project}` a project's slug or `prj_` id. Ids carry a prefix: `usr_`, `team_`, `prj_`, `dpl_`, `dom_`, `rec_`, `tok_`, `op_`.
- Send JSON with `Content-Type: application/json`. Timestamps are RFC 3339 UTC.

## Rules

1. Send an `Idempotency-Key` (8 to 128 printable characters; a new UUID per change) on the POSTs that take one (each is marked below). If a request fails or times out, retry it with the SAME key and body. The same key with a different body is `422`; while the first is still running it is `409`.
2. A deployment is created at once (`202`) and then builds: poll `GET /teams/{team}/projects/{project}/deployments/{deployment}` every few seconds, or follow `.../logs/stream` (Server-Sent Events), until `state` is `ready`, `failed` or `canceled`. Other slow changes return an operation: poll `GET /operations/{operation}` until `state` is `succeeded` or `failed`.
3. Lists take `limit` (1 to 100) and `cursor`, and return `items` and `next_cursor`. Follow `next_cursor` until it is null before deciding something does not exist.
4. Errors are RFC 9457 problem documents (`application/problem+json`) with `status`, `title`, `detail` and `request_id`. A `422` lists every bad field in `errors[{field, message}]`. A `402` has `code: plan_required`, `required_plan: pro` and `feature`: the team's plan doesn't include it; tell the human. A team you can't see is `404`, not `403`.
5. On `429`, wait `Retry-After` seconds. `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Scope` say which budget you are spending. On `500` or `503`, retry with backoff (and the same `Idempotency-Key`). On any other 4xx, fix the request; do not repeat it unchanged.
6. Never guess a slug or an id: read them from `GET /me` and the list endpoints.
7. Ask a human before anything destructive or visible to their users: deleting a project, domain, variable or flag; promoting or rolling back production; pausing a project; changing production's environment variables. Revealing or pulling variable values exposes secrets: do it only when asked, and never log them.

## Common jobs

- **Deploy now:** `POST /teams/{team}/projects/{project}/deployments` (optionally `branch`) builds a branch's newest commit; the production branch deploys to production, any other to a preview. Follow it as in rule 2. Read `url` when it is `ready`.
- **Why did a build fail:** `GET .../deployments/{deployment}` for its `failure` and steps, then `GET .../deployments/{deployment}/logs`.
- **Roll back:** list production deployments, then `POST .../deployments/{deployment}/rollback` with an earlier one. It answers with `undo` for `POST .../production`.
- **Set a variable:** `POST .../env` with `variables: [{key, value, environments}]`, then redeploy (`POST .../deployments/{deployment}/redeploy`) for it to apply.
- **Add a domain:** `POST /teams/{team}/domains`, show the human its `required_record` (or the nameservers, for Orbits DNS), then `POST /teams/{team}/domains/{domain}/checks` until `state` is `valid`.
- **What happened:** `GET /teams/{team}/activity`; runtime logs: `GET .../projects/{project}/logs`.

## Endpoints

100 operations, grouped as in the reference. `(read)` works with any token; `(full)` needs a `full` token. Those marked Idempotency-Key take that header.

### Teams and account

- `GET /me` (read): Current user. Returns 200.
- `GET /teams` (read): Teams the caller belongs to. Query: limit, cursor. Returns 200.
- `GET /teams/{team}` (read): Get a team. Returns 200.
- `PATCH /teams/{team}` (full): Rename, change slug, avatar, default region, or security rules. Body: name, slug, avatar_url, default_region, require_two_factor, session_max_age_days, inviters, sign_in_methods, notifications. Returns 200.
- `GET /teams/{team}/overview` (read): Dashboard overview for a time range. Query: range. Returns 200.
- `GET /teams/{team}/notifications` (read): Notifications for the caller in this team. Query: limit, cursor, unread. Returns 200.
- `POST /teams/{team}/notifications` (full, Idempotency-Key): Mark notifications read. Body: ids, all. Returns 204, no body.

### Projects

- `GET /templates` (read): Starter templates for a new project. Returns 200.
- `GET /teams/{team}/projects` (read): List projects. Query: limit, cursor, q, sort, repository. Returns 200.
- `POST /teams/{team}/projects` (full, Idempotency-Key): Create a project from a repository or a template. Body: name (required), slug, workload, source, template, source_kind, build, region, env. Returns 202.
- `GET /teams/{team}/projects/{project}` (read): Get a project. Returns 200.
- `PATCH /teams/{team}/projects/{project}` (full): Change project settings. Body: name, workload, source, build, git, node_version, preview_protection, preview_password, region. Returns 200.
- `DELETE /teams/{team}/projects/{project}` (full): Delete a project. Returns 202.
- `GET /teams/{team}/projects/{project}/deletion-impact` (read): What deleting a project removes. Returns 200.
- `POST /teams/{team}/projects/{project}/pause` (full, Idempotency-Key): Pause or resume a project. Body: paused (required). Returns 200.

### Deployments

- `GET /teams/{team}/deployments` (read): Deployments across the team's projects. Query: limit, cursor, q, project, environment, state, author. Returns 200.
- `GET /teams/{team}/projects/{project}/deployments` (read): A project's deployments. Query: limit, cursor, q, environment, state, branch, live. Returns 200.
- `POST /teams/{team}/projects/{project}/deployments` (full, Idempotency-Key): Deploy a branch now. Body: branch. Returns 202.
- `POST /teams/{team}/projects/{project}/uploads` (full, Idempotency-Key): Start dropping a site or app. Body: size (required), filename. Returns 201.
- `POST /teams/{team}/projects/{project}/uploads/{upload}/complete` (full, Idempotency-Key): Deploy a dropped archive. Returns 202.
- `DELETE /teams/{team}/projects/{project}/uploads/{upload}` (full): Cancel a drop. Returns 204, no body.
- `POST /teams/{team}/projects/{project}/production` (full, Idempotency-Key): Set what production serves. Body: deployment_id (required), auto_deploy_paused (required). Returns 200.
- `GET /teams/{team}/projects/{project}/deployments/{deployment}` (read): A deployment and its build steps. Returns 200.
- `GET /teams/{team}/projects/{project}/deployments/{deployment}/logs` (read): Build log lines. Query: after, limit. Returns 200.
- `GET /teams/{team}/projects/{project}/deployments/{deployment}/logs/stream` (read): Follow a build live (server-sent events). Query: after. Returns 200, a text/event-stream stream.
- `GET /teams/{team}/projects/{project}/deployments/{deployment}/screenshot` (read): A deployment's screenshot. Returns 200, image/jpeg.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/redeploy` (full, Idempotency-Key): Build the same commit again. Body: use_cache. Returns 202.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/promote` (full, Idempotency-Key): Promote to production. Returns 202.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/rollback` (full, Idempotency-Key): Roll production back. Returns 200.
- `POST /teams/{team}/projects/{project}/deployments/{deployment}/cancel` (full, Idempotency-Key): Cancel a build. Returns 202.

### Environment variables

- `GET /teams/{team}/projects/{project}/env` (read): List variables. Query: limit, cursor, environment, q. Returns 200.
- `POST /teams/{team}/projects/{project}/env` (full, Idempotency-Key): Add variables, or import a .env file. Body: variables (required), on_conflict. Returns 201.
- `PATCH /teams/{team}/projects/{project}/env/{key}` (full): Change a value or its environments. Body: value, environments. Returns 200.
- `DELETE /teams/{team}/projects/{project}/env/{key}` (full): Delete a variable. Returns 200.
- `POST /teams/{team}/projects/{project}/env/{key}/restore` (full, Idempotency-Key): Undo a delete. Returns 200.
- `POST /teams/{team}/projects/{project}/env/{key}/reveal` (full): Reveal a value. Returns 200.
- `POST /teams/{team}/projects/{project}/env/pull` (full): Download values for local development (`orbits env pull`). Body: environment (required). Returns 200.

### Domains

- `GET /teams/{team}/projects/{project}/branch-addresses` (read): A project's branch addresses. Returns 200.
- `GET /teams/{team}/domains` (read): The team's domains. Query: q, state, dns, project. Returns 200.
- `POST /teams/{team}/domains` (full, Idempotency-Key): Add a domain. Body: domain (required), dns, project, branch, to. Returns 200.
- `GET /teams/{team}/domains/preview` (read): What adding a domain would do. Query: domain (required), dns. Returns 200.
- `GET /teams/{team}/domains/{domain}` (read): A domain. Returns 200.
- `PATCH /teams/{team}/domains/{domain}` (full): Change what a domain serves. Body: project, branch, to. Returns 200.
- `DELETE /teams/{team}/domains/{domain}` (full): Remove a domain. Returns 204, no body.
- `POST /teams/{team}/domains/{domain}/checks` (full): Look for the domain's DNS now. Returns 200.

### DNS

- `GET /teams/{team}/domains/{domain}/records` (read): A zone's records. Returns 200.
- `POST /teams/{team}/domains/{domain}/records` (full, Idempotency-Key): Add a record. Body: type (required), name (required), value (required), ttl (required). Returns 201.
- `PUT /teams/{team}/domains/{domain}/records/{record}` (full): Edit a record. Body: type (required), name (required), value (required), ttl (required). Returns 200.
- `DELETE /teams/{team}/domains/{domain}/records/{record}` (full): Delete a record. Returns 204, no body.
- `POST /teams/{team}/domains/{domain}/zone-imports` (full, Idempotency-Key): Import a BIND zone file. Body: zone (required), dry_run. Returns 200.
- `GET /teams/{team}/domains/{domain}/email` (read): The Email setup dialog. Returns 200.
- `PUT /teams/{team}/domains/{domain}/email` (full): Set up email for a zone. Body: provider (required). Returns 200.

### Runtime logs and observability

- `GET /teams/{team}/projects/{project}/logs` (read): Runtime logs. Query: q, source, level, status, range, limit, cursor. Returns 200.
- `GET /teams/{team}/projects/{project}/logs/{log}` (read): One runtime log entry. Returns 200.
- `GET /teams/{team}/projects/{project}/observability` (read): Production's requests, errors and latency. Query: range, route, status, region. Returns 200.

### Analytics and Speed Insights

- `GET /teams/{team}/projects/{project}/analytics` (read): A project's visitors and page views. Query: range. Returns 200.
- `PUT /teams/{team}/projects/{project}/analytics` (full): Turn Analytics on or off. Body: enabled (required). Returns 200.
- `GET /teams/{team}/projects/{project}/analytics/event` (read): One custom event and its properties. Query: name (required), range. Returns 200.
- `GET /teams/{team}/projects/{project}/speed-insights` (read): A project's Web Vitals from real visits. Query: range, device. Returns 200.
- `PUT /teams/{team}/projects/{project}/speed-insights` (full): Turn Speed Insights on or off. Body: enabled (required). Returns 200.

### Feature flags

- `GET /teams/{team}/projects/{project}/flags` (read): A project's feature flags. Query: q, type. Returns 200.
- `POST /teams/{team}/projects/{project}/flags` (full, Idempotency-Key): Create a flag. Body: key (required), type (required), description, environments. Returns 201.
- `GET /teams/{team}/projects/{project}/flag-keys` (read): Each environment's ORBITS_FLAGS key. Returns 200.
- `GET /teams/{team}/projects/{project}/flags/{flag}` (read): A flag, its history and who it was checked for. Returns 200.
- `PATCH /teams/{team}/projects/{project}/flags/{flag}` (full): Change a flag's description. Body: description. Returns 200.
- `DELETE /teams/{team}/projects/{project}/flags/{flag}` (full): Delete a flag. Returns 204, no body.
- `PUT /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}` (full): Switch a flag, set its rollout or its value in one environment. Body: on, rollout, value. Returns 200.
- `POST /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules` (full, Idempotency-Key): Add a targeting rule. Body: attribute (required), operator (required), values (required), serve (required). Returns 201.
- `PATCH /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}` (full): Change what a rule serves. Body: serve (required). Returns 200.
- `DELETE /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}` (full): Remove a rule. Returns 204, no body.

### Workflows

- `GET /teams/{team}/projects/{project}/workflows` (read): A project's workflows and recent runs. Returns 200.
- `POST /teams/{team}/projects/{project}/workflows/{workflow}/runs` (full, Idempotency-Key): Run a workflow now. Body: input. Returns 201.
- `GET /teams/{team}/projects/{project}/workflows/runs/{run}` (read): One run and its steps. Returns 200.
- `POST /teams/{team}/projects/{project}/workflows/runs/{run}/cancel` (full, Idempotency-Key): Cancel a running run. Returns 200.
- `POST /teams/{team}/projects/{project}/workflows/runs/{run}/retry` (full, Idempotency-Key): Retry a failed run from the step that failed. Returns 200.

### Sandboxes

- `GET /teams/{team}/projects/{project}/sandboxes` (read): A project's sandboxes. Returns 200.
- `POST /teams/{team}/projects/{project}/sandboxes` (full, Idempotency-Key): Start a sandbox. Body: name (required), runtime (required), size (required), clone, env, stop_after. Returns 201.
- `GET /teams/{team}/projects/{project}/sandboxes/{sandbox}` (read): A sandbox, its usage and open ports. Returns 200.
- `DELETE /teams/{team}/projects/{project}/sandboxes/{sandbox}` (full): Delete a sandbox. Returns 204, no body.
- `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/stop` (full, Idempotency-Key): Suspend a sandbox. Returns 200.
- `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/start` (full, Idempotency-Key): Resume a sandbox. Returns 200.
- `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket` (full): A ticket to open the sandbox's terminal. Returns 200.

### Alerts

- `GET /teams/{team}/projects/{project}/alerts` (read): A project's alert rules and their state. Returns 200.
- `POST /teams/{team}/projects/{project}/alerts` (full, Idempotency-Key): Create an alert rule. Body: name (required), metric (required), threshold (required), window_minutes (required), channels (required), direction, routes, on. Returns 201.
- `POST /teams/{team}/projects/{project}/alerts/preview` (full, Idempotency-Key): How much traffic a draft rule would see. Body: metric (required), window_minutes (required), direction, routes. Returns 200.
- `PATCH /teams/{team}/projects/{project}/alerts/{alert}` (full): Change or switch an alert rule. Body: name, metric, direction, threshold, window_minutes, routes, channels, on. Returns 200.
- `DELETE /teams/{team}/projects/{project}/alerts/{alert}` (full): Delete an alert rule. Returns 204, no body.
- `GET /teams/{team}/projects/{project}/alerts/{alert}/events` (read): When a rule fired and resolved. Query: limit, cursor. Returns 200.
- `GET /teams/{team}/alert-channels` (read): The team's alert webhook. Returns 200.
- `PUT /teams/{team}/alert-channels/webhook` (full): Set the team's alert webhook. Body: url (required), rotate_secret. Returns 200.
- `DELETE /teams/{team}/alert-channels/webhook` (full): Remove the team's alert webhook. Returns 204, no body.
- `POST /teams/{team}/alert-channels/webhook/test` (full, Idempotency-Key): Send a test event to the webhook. Returns 200.

### Integrations

- `GET /teams/{team}/integrations` (read): Catalog with installed state. Returns 200.

### Billing

- `GET /plans` (read): The plans and their prices. Returns 200.
- `GET /teams/{team}/billing` (read): The team's plan and billing state. Returns 200.
- `GET /teams/{team}/billing/invoices` (read): The team's invoices. Query: limit. Returns 200.
- `GET /teams/{team}/billing/invoices/{invoice}` (read): One invoice, as a receipt. Returns 200.

### Usage, activity and operations

- `GET /teams/{team}/usage` (read): A month of the team's usage, by day and by project. Query: month. Returns 200.
- `GET /teams/{team}/activity` (read): Team activity feed. Query: q, actor, project, type, since, limit, cursor. Returns 200.
- `GET /operations/{operation}` (read): Poll an asynchronous operation. Returns 200.
