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

    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:

    Terminal
    $ 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:

    Terminal
    $ 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 full or read access, 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; a 422 names 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: 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.

    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.

    Was this page helpful?

    Updated