API reference · Using the APIOverview
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.
The Orbits API is what the CLI, the SDKs and the MCP server 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.
https://api.theorbits.app/v1Staging, 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:
$ 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:
$ 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. - One token, one team. A token acts as the person who made it, in one team, with
fullorreadaccess, and can be limited to one project. A few things are never a token's: see Authentication. - Errors are problem documents (RFC 9457) with a
request_id; a422names every bad field. See 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:
limitandcursorin,itemsandnext_cursorout. - Rate limits are per person, per token and per team, and every answer says what is left. See 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.
To take the whole API with you, download the OpenAPI contract or a Postman, Insomnia or Bruno collection. Building an AI agent? Start with Using the API from an AI agent.