SDKsPython
Python SDK
Install useorbits, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries, sync or async.
import useorbits
with useorbits.Orbits() as orbits:
for project in orbits.projects.list_all("my-team"):
print(project["slug"], project["status"], project["free_address"])useorbits is the official Python library. It has sync (Orbits) and asyncio (AsyncOrbits) clients with the same methods, typed keyword arguments, and results typed with the TypedDicts in useorbits.types, keyed exactly as the API names its fields. Its one dependency is httpx. It needs Python 3.10 or later.
Every route under a team takes the team's slug (or team_ id) first, then the project's slug (or prj_ id) where there is one. Other arguments are keyword-only. Arguments you leave out are not sent; passing None sends JSON null.
Install
$ pip install useorbitsAuthenticate
Make an API token under Team › Settings › API tokens and put it in ORBITS_TOKEN. The client reads it.
$ export ORBITS_TOKEN=orb_live_…Without a token, useorbits.Orbits() raises. Or pass options:
import os
import useorbits
orbits = useorbits.Orbits(
token=os.environ["MY_ORBITS_TOKEN"],
base_url="https://stagingapi.theorbits.app/v1", # or ORBITS_API_URL; default https://api.theorbits.app/v1
timeout=60.0, # per attempt, in seconds (the default; 10 s to connect); or an httpx.Timeout
max_retries=3, # the default
)The other options are default_headers, user_agent and http_client. Every method also takes timeout=, extra_headers=, extra_query= and, with a body, extra_body=. POSTs take idempotency_key=. Use the client as a context manager, as above, or call close() when you are done.
Deploy and follow the build
For a Git project, deployments.create builds a branch's newest commit, by default the production branch:
import useorbits
with useorbits.Orbits() as orbits:
deployment = orbits.deployments.create("my-team", "my-app")
# or a preview: orbits.deployments.create("my-team", "my-app", branch="feature/checkout")
for event in orbits.deployments.stream_logs("my-team", "my-app", deployment["id"]):
if event["event"] == "line":
print(event["data"]["text"])
elif event["event"] == "done":
break
ready = orbits.wait_for_deployment("my-team", "my-app", deployment) # raises DeploymentFailedError if it fails
print(ready["url"])stream_logs yields the build's events (line, steps, done, then screenshot) and reconnects if the connection drops, without missing or repeating a line. get_logs(..., after=n) reads the log without streaming. deployments.get(team, project, deployment) reads one deployment.
Deploy a folder
A project created with source_kind="upload" deploys from files instead of a repository:
project = orbits.projects.create("my-team", name="my-site", source_kind="upload")
deployment = orbits.deployments.upload_dir("my-team", project["slug"], "./dist")
orbits.wait_for_deployment("my-team", project["slug"], deployment)
print("Live at https://" + project["free_address"])upload_dir zips the folder, leaving out node_modules, .git, .next and __MACOSX at any depth, links, and whatever an .orbitsignore at the folder's root lists (.gitignore syntax). It sends the archive straight to storage, without your API token, then deploys it to production. upload_archive takes a zip you made yourself.
Promote, roll back, redeploy
orbits.deployments.promote("my-team", "my-app", "dpl_…") # a preview to production, as a new build
orbits.deployments.rollback("my-team", "my-app", "dpl_…") # production back to an earlier build, at once
orbits.deployments.redeploy("my-team", "my-app", "dpl_…", use_cache=False)
orbits.deployments.cancel("my-team", "my-app", "dpl_…")A rollback pauses automatic production deploys. See Deployments.
Environment variables
import os
orbits.env.create(
"my-team",
"my-app",
variables=[
{"key": "STRIPE_SECRET_KEY", "value": os.environ["STRIPE_SECRET_KEY"]}, # sensitive by default
{"key": "API_URL", "value": "https://api.example.com", "sensitive": False, "environments": ["production"]},
],
)
for var in orbits.env.list_all("my-team", "my-app"):
print(var["key"], var["environments"], var["sensitive"])Variables are sensitive (write-only) unless "sensitive": False, and apply to production and preview unless you set environments. A key that exists already raises ConflictError; pass on_conflict="replace" to replace it. New values apply to deployments built afterwards, so redeploy to use them. Values are never listed; env.reveal reads one non-sensitive value and env.pull(team, project, environment="development") an environment's readable values, both with a full-access token. See Environment variables.
Domains
domain = orbits.domains.add("my-team", domain="shop.example.com", project="my-app")
print(domain["state"], domain["required_record"])
orbits.domains.check("my-team", "shop.example.com") # look the DNS up again nowbranch= serves a branch's newest preview instead of production, and to= redirects to another hostname. Records on Orbits DNS are under domains.records. See Custom domains.
Resources
Areas are attributes of the client and nest where the API does:
| Attribute | What it covers |
|---|---|
me | The person the token acts as |
teams, teams.notifications | Teams, their overview and notifications |
projects | Create, configure, pause/resume, delete |
deployments, deployments.uploads | List, deploy, upload_dir, logs and stream_logs, promote, rollback, redeploy, cancel, set_production, wait |
env | Environment variables: list, create, update, delete, restore, reveal, pull |
domains, domains.records, domains.email | Domains, checks, zone imports, DNS records, email provider records |
flags, flags.rules | Feature flags and their targeting rules |
workflows | Workflows and their runs |
alerts, alerts.channels | Alerts and where they are sent |
observability | Runtime logs, request metrics, Analytics, Speed Insights |
usage, activity, billing, billing.invoices | Usage, the activity log, the plan and invoices (read only) |
templates, integrations, operations | Starter templates, the integrations list, operations |
There is a sandboxes attribute too, but sandboxes are not available yet.
Async
AsyncOrbits has the same methods; lists are async iterators:
import asyncio
import useorbits
async def main() -> None:
async with useorbits.AsyncOrbits() as orbits:
async for deployment in orbits.deployments.list_all("my-team", "my-app", environment="production"):
print(deployment["id"], deployment["state"])
asyncio.run(main())Errors
try:
orbits.projects.get("my-team", "my-app")
except useorbits.NotFoundError as err:
print(err.detail, err.request_id) # also "not in your team": the API doesn't tell the two apart
except useorbits.ValidationError as err:
for field in err.errors:
print(field["field"], field["message"])
except useorbits.ForbiddenError as err:
print(err.detail) # e.g. "This API token is read-only"
except useorbits.APIError as err:
print(err.status, err.title, err.detail)APIError carries status, title, detail (safe to show), type, instance, code (a stable reason where there is one, such as plan_required), request_id (quote it to support) and errors.
| Class | When |
|---|---|
BadRequestError | 400 |
AuthenticationError | 401: the token is wrong, revoked or expired |
PaymentRequiredError | 402: the team's plan doesn't include this (required_plan, feature) |
ForbiddenError | 403 |
NotFoundError | 404: not there, or not in the token's team |
ConflictError | 409 |
ValidationError | 422, with errors |
RateLimitError | 429 after the retries, with retry_after and scope |
ServerError | 5xx after the retries |
APIConnectionError, APITimeoutError | No answer |
UploadError | Storage refused an upload |
OperationFailedError, DeploymentFailedError, WaitTimeoutError | Waiting ended badly |
All of them are OrbitsError. Errors.
Pages
list() returns one page, with items and next_cursor. list_all() follows the cursor for you:
for d in orbits.deployments.list_all("my-team", "my-app", environment="production"):
print(d["id"], d["state"])Waiting
Slow changes answer 202 with an operation or the new deployment:
accepted = orbits.projects.delete("my-team", "old-site")
orbits.wait_for_operation(accepted, timeout=300) # raises OperationFailedError if it failed
orbits.wait_for_deployment("my-team", "my-app", "dpl_…", timeout=900)wait_for_deployment polls every 3 seconds for up to 30 minutes, and wait_for_operation every 2 seconds for up to 10 minutes. Both take timeout= and poll_interval= in seconds, and raise_on_failure=False to get the result back instead of an error. A wait that runs out raises WaitTimeoutError; the change may still finish. They are also deployments.wait and operations.wait.
Idempotency and retries
Every POST gets a fresh UUID Idempotency-Key, and retries resend the same key, so the API returns the first result instead of repeating the change. Connection errors, timeouts, 429, 502, 503 and 504 are retried up to max_retries times with a growing, random wait, or after the Retry-After the API sends (at most 60 seconds). GET, PUT and DELETE are safe to repeat; a PATCH is retried only when the API certainly did nothing (a 429, or a connection that was never made).
Requests carry User-Agent: orbits-python/<version>. The token is never logged.
Calling any endpoint
request calls a path directly, with the same auth, retries and errors:
page = orbits.request("GET", "/teams/my-team/projects", query={"q": "shop"})