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.
| Language | Install | Import |
|---|---|---|
| JavaScript and TypeScript | npm install @useorbits/sdk | import { Orbits } from "@useorbits/sdk" |
| Python | pip install useorbits | import useorbits |
| Go | go get github.com/The-Orbits/orbits-go | orbits "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. SetORBITS_API_URL, or pass a base URL, to use another, such as staging athttps://stagingapi.theorbits.app/v1. - Adds an
Idempotency-Keyto everyPOST. 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,503and504, up to 3 times with a growing, random wait, or after theRetry-Afterthe 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, therequest_idand 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,.nextand what.orbitsignorelists, 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.