OrbitsDocs
esc
    Open Orbits
    API reference · Using the APIAI agents

    Using the API from an AI agent

    Connect an AI app through MCP, build an agent on the SDKs, or give any agent one link, a token limited to what it should do, and the rules that keep it from doing harm.

    An AI agent can manage your apps through this API the same way a script does. There are three ways in, easiest first.

    Connect an AI app with MCP

    If your AI app or editor speaks MCP, connect it to the Orbits MCP server:

    text
    https://mcp.theorbits.app/mcp

    It gives the app ready-made tools for projects, deployments, logs, variables and domains, and anything that changes production or deletes something asks you first. Step-by-step setup for each app, and how to run the server on your own machine instead: Connect your AI.

    Build your own agent on an SDK

    Writing the agent yourself? The SDKs for JavaScript (@useorbits/sdk), Python (useorbits) and Go handle idempotency keys, safe retries, pagination and waiting for deployments, so your tools only describe what to do.

    Any other agent

    For an agent that can only make HTTP calls, the rest of this page is what to give it, and what to tell it.

    The agent brief is everything an agent needs in one Markdown file: the base URL, how to authenticate, the rules it must follow, common jobs step by step, and every endpoint with the token it needs, its parameters and what it returns. It is generated from the API's contract, so it is always current. Agents that read OpenAPI can take the contract too, and the whole site is in /llms.txt and /llms-full.txt.

    Give it a token for the job

    Make a token for the agent alone, under Team › Settings › API tokens, with as little as the job needs:

    • Read access if it only has to look: a read token can't change anything and never sees environment variable values.
    • One project, if the job is about one project.
    • An expiry of 30 days, rather than never.

    Revoke it when the job is done. A token can never manage tokens, members or the team's security, so an agent can't give itself more access. See Authentication.

    Tell it the rules

    Put these in the agent's instructions, or check that its brief covers them:

    1. Ask before anything that changes production or deletes: promoting, rolling back, pausing or deleting a project, deleting domains, variables or flags.
    2. Treat variable values as secrets: reveal or pull them only when asked, and never print or log them.
    3. Send an Idempotency-Key on the POSTs that take one, and the same key when retrying (Conventions).
    4. Follow next_cursor to the end of a list before deciding something doesn't exist.
    5. On 429, wait Retry-After seconds; on a 4xx, fix the request instead of repeating it (Errors).

    Was this page helpful?

    Updated