OrbitsDocs
esc
    Open Orbits
    SDKsOverview

    SDKs

    Official Orbits libraries for JavaScript and TypeScript, Python and Go. They handle the token, retries, idempotency, pagination, uploads and waiting for you.

    The SDKs call the Orbits API for you. You write "deploy this branch"; they add the headers, retry safely, follow pages and wait for the build to finish.

    LanguageInstallImport
    JavaScript and TypeScriptnpm install @useorbits/sdkimport { Orbits } from "@useorbits/sdk"
    Pythonpip install useorbitsimport useorbits
    Gogo get github.com/The-Orbits/orbits-goorbits "github.com/The-Orbits/orbits-go"

    All three are open source, under the MIT licence, in the The-Orbits organisation on GitHub.

    What every SDK does

    • Reads your token from ORBITS_TOKEN. Or pass it in. An owner or admin makes one under Team › Settings › API tokens. See API tokens.
    • Talks to https://api.theorbits.app/v1. Set ORBITS_API_URL, or pass a base URL, to use another, such as staging at https://stagingapi.theorbits.app/v1.
    • Adds an Idempotency-Key to every POST. A fresh UUID per call, reused on each retry, so a retry never makes a change twice. Why it matters.
    • Retries what is safe to retry. Connection errors, timeouts, 429, 502, 503 and 504, up to 3 times with a growing, random wait, or after the Retry-After the API sends (at most a minute).
    • Turns errors into typed errors with the HTTP status, the title, the detail (safe to show to people), the stable code, the request_id and any field errors. Errors.
    • Follows pages for you. Loop over every item; the SDK follows next_cursor.
    • Deploys a folder. Zips it, leaving out node_modules, .git, .next and what .orbitsignore lists, uploads it straight to storage without your token, and starts the deployment. See Upload a folder.
    • Follows a build log as it is written, and reconnects where it left off if the connection drops.
    • Waits for changes. Polls a deployment until it is ready, failed or canceled, or an operation (such as deleting a project) until it finishes, and raises an error if it failed.
    • Never logs your token or the values of your environment variables.

    Every operation an API token can use has a method. Things no token can do, by design, have none: signing in, managing tokens, members and invites, moving a project to another team, payments, and integrations beyond the list. Each SDK can also send a raw request to any path, with the same auth, retries and errors.

    Sandboxes have methods too, but sandboxes are not available yet, so those calls fail until they are.

    What a token can do

    A token belongs to one team. A read token can only read, and never reads environment variable values. A token limited to one project reaches only that project; anything else answers "not found". Requests carry the SDK's name and version in User-Agent, which Settings › API tokens shows as the token's last use.

    Which one to use

    Use the language your project already uses. All three do the same things. For a few calls from a shell script or CI, the CLI may be simpler. To let an AI app manage your projects, see Connect your AI.

    To add Analytics, Speed Insights, feature flags or workflows to your app itself, use the in-app packages instead (@useorbits/analytics, @useorbits/speed-insights, @useorbits/flags, @useorbits/workflows). See Analytics, Speed Insights, Feature flags and Workflows.

    Was this page helpful?

    Updated