# API reference

The Orbits REST API, for scripts, CI and your own tools. Everything an API token can do, with examples in cURL and the JavaScript, Python and Go SDKs.

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

The Orbits API is what the [CLI](https://docs.orbits.africa/cli), the [SDKs](https://docs.orbits.africa/sdks) and the [MCP server](https://docs.orbits.africa/ai/connect-your-ai) use. Anything an API token can do in Orbits, you can do with a request: create projects, start and follow deployments, roll production back, set environment variables, add domains and DNS records, read logs, analytics and usage, and manage flags, workflows and alerts.

```text
https://api.theorbits.app/v1
```

Staging, for trying a change against Orbits' staging environment, is `https://stagingapi.theorbits.app/v1`. Its accounts and data are separate from production's.

## A first request

Make an API token in the dashboard under **Team › Settings › API tokens** (owners and admins can), then:

```console
$ export ORBITS_TOKEN=orb_live_…
$ curl https://api.theorbits.app/v1/me \
    -H "Authorization: Bearer $ORBITS_TOKEN"
```

The answer is you, with the one team the token reaches. Every other route is under `/v1/teams/{team}/…`, where `{team}` is that team's slug or its `team_` id:

```console
$ curl https://api.theorbits.app/v1/teams/my-team/projects \
    -H "Authorization: Bearer $ORBITS_TOKEN"
```

## How it works

- **REST and JSON.** Send JSON with `Content-Type: application/json`; times are RFC 3339 in UTC. See [Conventions](https://docs.orbits.africa/api/conventions).
- **One token, one team.** A token acts as the person who made it, in one team, with `full` or `read` access, and can be limited to one project. A few things are never a token's: see [Authentication](https://docs.orbits.africa/api/authentication).
- **Errors are problem documents** (RFC 9457) with a `request_id`; a `422` names every bad field. See [Errors](https://docs.orbits.africa/api/errors).
- **Slow work answers `202`.** A new deployment comes back at once, queued; poll it or follow its build log stream. Other slow changes return an operation to poll.
- **Lists page with a cursor:** `limit` and `cursor` in, `items` and `next_cursor` out.
- **Rate limits** are per person, per token and per team, and every answer says what is left. See [Rate limits](https://docs.orbits.africa/api/rate-limits).

## The reference

Each page below is generated from the API's OpenAPI contract, so it lists exactly what the API takes and returns: every endpoint's parameters, body and response fields, an example request in cURL and each SDK, an example response, and the errors it can answer.

::::cards
:::card[Projects]{href=/api/projects}
Create, change, pause and delete projects.
:::
:::card[Deployments]{href=/api/deployments}
Deploy, follow the build, promote, roll back, redeploy, cancel.
:::
:::card[Environment variables]{href=/api/environment-variables}
Add, change, reveal and pull a project's variables.
:::
::::

::::cards
:::card[Domains]{href=/api/domains}
Custom domains, their DNS checks and branch addresses.
:::
:::card[Runtime logs]{href=/api/logs}
What your app prints and the requests it serves.
:::
:::card[Usage and activity]{href=/api/usage-and-activity}
What a team used, what happened, and operations.
:::
::::

To take the whole API with you, download the [OpenAPI contract or a Postman, Insomnia or Bruno collection](https://docs.orbits.africa/api/postman-openapi). Building an AI agent? Start with [Using the API from an AI agent](https://docs.orbits.africa/api/ai-agents).
