# Orbits > Orbits hosts web apps: connect a GitHub, GitLab or Bitbucket repository, or upload a folder, and get a live URL at .theorbits.app, with previews for every branch and pull request, custom domains, environment variables, runtime logs, analytics, Speed Insights, feature flags, workflows and alerts. Apps run in Abuja, Nigeria. Plans: Free, and Pro at $5 a month, paid in Naira. Its API is at https://api.theorbits.app/v1 and takes a team API token (Authorization: Bearer orb_live_…). The API's OpenAPI 3.1 contract: https://docs.orbits.africa/openapi/orbits-api.yaml (JSON: https://docs.orbits.africa/openapi/orbits-api.json); collections of it for Postman (https://docs.orbits.africa/postman/orbits-api.postman_collection.json), Insomnia (https://docs.orbits.africa/insomnia/orbits-api.insomnia.json) and Bruno (https://docs.orbits.africa/bruno/orbits-api.bruno.zip). Errors are RFC 9457 problem documents; lists use limit and cursor; slow changes answer 202. Agents: read https://docs.orbits.africa/agent-brief.md first, and "Using the API from an AI agent" before acting on anyone's apps. MCP clients can connect to the hosted MCP server at https://mcp.theorbits.app/mcp (https://docs.orbits.africa/ai/connect-your-ai; tools: https://docs.orbits.africa/ai/mcp-tools). CLI: orbits (https://docs.orbits.africa/cli). SDKs: JavaScript @useorbits/sdk, Python useorbits, Go (https://docs.orbits.africa/sdks). In-app packages: @useorbits/analytics, @useorbits/speed-insights, @useorbits/flags, @useorbits/workflows. --- # API reference Source: https://docs.orbits.africa/api 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](https://docs.orbits.africa/cli), the [SDKs](https://docs.orbits.africa/sdks) and the [MCP server](https://docs.orbits.africa/ai/connect-your-ai) 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: ```console $ 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: ```console $ 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](https://docs.orbits.africa/api/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](https://docs.orbits.africa/api/authentication). - **Errors are problem documents** (RFC 9457) with a `request_id`; a `422` names every bad field. See [Errors](https://docs.orbits.africa/api/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](https://docs.orbits.africa/api/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. ::::cards :::card[Projects]{href=/api/projects} Create, change, pause and delete projects. ::: :::card[Deployments]{href=/api/deployments} Deploy, follow the build, promote, roll back, redeploy, cancel. ::: :::card[Environment variables]{href=/api/environment-variables} Add, change, reveal and pull a project's variables. ::: :::: ::::cards :::card[Domains]{href=/api/domains} Custom domains, their DNS checks and branch addresses. ::: :::card[Runtime logs]{href=/api/logs} What your app prints and the requests it serves. ::: :::card[Usage and activity]{href=/api/usage-and-activity} What a team used, what happened, and operations. ::: :::: To take the whole API with you, download the [OpenAPI contract or a Postman, Insomnia or Bruno collection](https://docs.orbits.africa/api/postman-openapi). Building an AI agent? Start with [Using the API from an AI agent](https://docs.orbits.africa/api/ai-agents). --- # Authentication Source: https://docs.orbits.africa/api/authentication Send a team API token as a bearer token. What full and read tokens may do, project-limited tokens, and the few things no token can do. Every request carries an API token in the `Authorization` header: ```http Authorization: Bearer orb_live_… ``` A request without one, or with a token that is wrong, revoked or expired, answers `401`. ## Make a token API tokens are made in the dashboard, under **Team › Settings › API tokens**, by the team's owners and admins. Choose: - **Access:** `full` (deploy, change settings and domains) or `read` (see projects, deployments and logs). - **Project:** all of the team's projects, or one. - **Expires:** after 30, 90 or 365 days, or never. The token (`orb_live_` and 32 characters) is shown once, when it is made: Orbits keeps only a hash of it. Store it in your CI's secrets or a password manager. A team can have up to 50 active tokens. See [API tokens](https://docs.orbits.africa/team/api-tokens) for the guide. The CLI and the SDKs read the token from `ORBITS_TOKEN`; the examples in this reference do too. ## What a token acts as A token belongs to one team and acts as the person who made it. It can do what that person's role allows in that team, within its own access, and no more. It stops working when that person leaves the team, and while the team requires two-factor authentication and the person has it off. The team's rules on sign-in methods and session length apply to sessions, not tokens. `GET /v1/me` shows who the token acts as, and the one team (and project, for a project-limited token) it reaches. ## Full and read tokens | | `read` | `full` | | --- | --- | --- | | `GET` and `HEAD` requests | Yes | Yes | | Anything else (create, change, delete, deploy) | No: `403` "This API token is read-only" | Yes | | Environment variable values | Never (revealing and pulling are `POST`s) | Yes | Each operation in the reference says which it needs: **Read or full token**, or **Full token**. ## Project-limited tokens A token limited to one project reaches only that project's routes (`/v1/teams/{team}/projects/{project}/…` for that project), and `/v1/me` and the team list show it only that team and project. ## What no token can do Some things are only ever done by a signed-in person in the dashboard. A token that tries answers `403` ("API tokens can't use this endpoint" or "API tokens can't manage integrations"): - signing in, and the account routes (`/v1/auth/…`, `/v1/me/…`), such as your profile, email and two-factor settings; - creating teams, accepting or declining invites, and deleting the team; - making, listing or revoking API tokens; - managing members and invites; - the team's security rules: required two-factor, allowed sign-in methods, session length, and who can invite; - moving a project to another team; - connecting, changing or disconnecting Git and notification integrations (listing them, `GET /v1/teams/{team}/integrations`, is fine); - paying for, cancelling or resuming a plan (reading billing is fine). Outside a team, a token may call `GET /v1/me`, `GET /v1/teams`, `GET /v1/templates` and `GET /v1/operations/{operation}`. :::warning[Treat a token like a password] Anyone with a `full` token can deploy to your production and read your environment variables. Give each script or CI pipeline its own token, with `read` access or one project where that is enough, and revoke a token you no longer use, or that may have leaked, under **Team › Settings › API tokens**. ::: --- # Conventions Source: https://docs.orbits.africa/api/conventions Paths, ids, JSON, timestamps, Idempotency-Key, pagination, and how slow changes answer. ## Paths and ids Every path is under `https://api.theorbits.app/v1`, and a team's resources are under `/v1/teams/{team}/…`. Where a path takes `{team}` you may send the team's slug or its id; `{project}` is the project's slug or its id; `{domain}` the domain's name or its id. Ids carry a prefix that says what they are: | Prefix | Object | | --- | --- | | `usr_` | A user | | `team_` | A team | | `prj_` | A project | | `dpl_` | A deployment | | `dom_` | A domain | | `rec_` | A DNS record | | `tok_` | An API token | | `op_` | An operation | ## Requests and responses The API speaks JSON. Send bodies with `Content-Type: application/json`. Timestamps are RFC 3339 in UTC (`2026-11-10T09:30:00Z`); the dashboard shows them in Lagos time. Numbers are numbers, not formatted strings. A team you are not a member of, or a resource in it, answers `404`, never `403`: the API doesn't confirm that something exists to someone who can't see it. ## Idempotency-Key A `POST` that creates or starts something takes an `Idempotency-Key` header: a value of 8 to 128 printable characters, new for each change (a UUID is a good choice). If the request fails or times out, send it again with the same key and the same body. The rules: - The same key with the same request (method, path and body) replays the first successful answer instead of doing the work twice. - The same key with a different request answers `422` on `Idempotency-Key`, and nothing is applied. - While the first request with a key is still running, a second answers `409`. - A request that fails frees its key, so a retry runs it again. The SDKs and the CLI send a key on every request that takes one, and reuse it when they retry. :::note[Twenty-seven operations take an Idempotency-Key] - `POST /teams/{team}/notifications`: Mark notifications read. - `POST /teams/{team}/projects`: Create a project from a repository or a template. - `POST /teams/{team}/projects/{project}/pause`: Pause or resume a project. - `POST /teams/{team}/projects/{project}/deployments`: Deploy a branch now. - `POST /teams/{team}/projects/{project}/uploads`: Start dropping a site or app. - `POST /teams/{team}/projects/{project}/uploads/{upload}/complete`: Deploy a dropped archive. - `POST /teams/{team}/projects/{project}/production`: Set what production serves. - `POST /teams/{team}/projects/{project}/deployments/{deployment}/redeploy`: Build the same commit again. - `POST /teams/{team}/projects/{project}/deployments/{deployment}/promote`: Promote to production. - `POST /teams/{team}/projects/{project}/deployments/{deployment}/rollback`: Roll production back. - `POST /teams/{team}/projects/{project}/deployments/{deployment}/cancel`: Cancel a build. - `POST /teams/{team}/projects/{project}/env`: Add variables, or import a .env file. - `POST /teams/{team}/projects/{project}/env/{key}/restore`: Undo a delete. - `POST /teams/{team}/domains`: Add a domain. - `POST /teams/{team}/domains/{domain}/records`: Add a record. - `POST /teams/{team}/domains/{domain}/zone-imports`: Import a BIND zone file. - `POST /teams/{team}/projects/{project}/flags`: Create a flag. - `POST /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules`: Add a targeting rule. - `POST /teams/{team}/projects/{project}/workflows/{workflow}/runs`: Run a workflow now. - `POST /teams/{team}/projects/{project}/workflows/runs/{run}/cancel`: Cancel a running run. - `POST /teams/{team}/projects/{project}/workflows/runs/{run}/retry`: Retry a failed run from the step that failed. - `POST /teams/{team}/projects/{project}/sandboxes`: Start a sandbox. - `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/stop`: Suspend a sandbox. - `POST /teams/{team}/projects/{project}/sandboxes/{sandbox}/start`: Resume a sandbox. - `POST /teams/{team}/projects/{project}/alerts`: Create an alert rule. - `POST /teams/{team}/projects/{project}/alerts/preview`: How much traffic a draft rule would see. - `POST /teams/{team}/alert-channels/webhook/test`: Send a test event to the webhook. ::: `PUT`, `PATCH` and `DELETE` requests don't take the header: sending them twice has the same effect as sending them once. Neither do revealing a variable, pulling variables and checking a domain, which change nothing. ## Pagination Lists take `limit` (from 1 to 100, 25 by default) and `cursor`, and answer `items` and `next_cursor`. To read everything, send the `next_cursor` you got as `cursor` until it is `null`: ```console $ curl "https://api.theorbits.app/v1/teams/my-team/projects?limit=100" \ -H "Authorization: Bearer $ORBITS_TOKEN" $ curl "https://api.theorbits.app/v1/teams/my-team/projects?limit=100&cursor=" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` A cursor is opaque: don't build or change one. The SDKs have helpers that follow cursors for you. ## Slow changes: 202 Anything that takes a while answers `202` as soon as it is recorded: what you asked for is accepted, and the work happens next. - **Deployments.** Creating, redeploying or promoting answers the new deployment, `queued`. Poll `GET …/deployments/{deployment}` every few seconds, or follow `GET …/deployments/{deployment}/logs/stream` (Server-Sent Events), until its `state` is `ready`, `failed` or `canceled`. - **Operations.** Other slow changes answer an operation (`op_…`). Poll `GET /v1/operations/{operation}` until its `state` is `succeeded` or `failed`; a failed one carries an `error`. What is running is reported separately from what was asked for: a deployment's `state` and its runtime are written by Orbits, never by you. ## Planned operations A few operations in the contract are planned and not served yet. The reference shows them, marked **Planned: not available yet**, so you can see what is coming; calling one today answers an error. None of the operations in this reference is planned today. --- # Errors Source: https://docs.orbits.africa/api/errors Every error is an RFC 9457 problem document with a request id. What each status means, the 422 field list, and the 402 plan answer. An error answers a `4xx` or `5xx` status with a problem document (RFC 9457), `Content-Type: application/problem+json`: ```json { "type": "about:blank", "title": "unprocessable entity", "status": 422, "detail": "Validation failed", "request_id": "9f2c4e1a7b3d4c58", "errors": [ { "field": "slug", "message": "slug must be 3-40 lowercase letters, digits or hyphens" } ] } ``` | Field | What it holds | | --- | --- | | `type`, `title`, `status` | Always there. `type` is `about:blank`, `title` the status's name, and `status` repeats the HTTP status. | | `detail` | What went wrong, in words you can show a person. A `500` leaves it out rather than say anything about Orbits' internals. | | `request_id` | The request's id. Quote it when you ask for [help](https://docs.orbits.africa/help/support). | | `errors` | On a `422`: one entry per bad field, `{field, message}`. | | `code` | A stable reason, where one is defined: `plan_required` on a `402`; `price_changed` and `already_pro` (`409`) and `billing_unavailable` (`503`) from billing. | | `required_plan`, `feature` | On a `402`: the plan that includes it (`pro`) and what is missing (`functions`, `sandboxes`, `analytics` or `speed_insights`). | Act on the status and on `code` where there is one, not on the wording of `detail`, which can change. ## Statuses | Status | Meaning | What to do | | --- | --- | --- | | `400` | The request is malformed: not JSON, or a parameter of the wrong kind. | Fix the request. | | `401` | No token, or the token is wrong, revoked or expired. | Check `Authorization: Bearer orb_live_…`; make a new token if it was revoked or expired. | | `402` | The team's plan doesn't include this. | See `feature`; the team's owner can move it to [Pro](https://docs.orbits.africa/billing/plans). | | `403` | You are in the team, but not allowed this: your role, a `read` token writing, a project-limited token outside its project, something no token may do, or the team requires two-factor and the token's owner has it off. | Read `detail`. See [Authentication](https://docs.orbits.africa/api/authentication). | | `404` | It doesn't exist, or you can't see it. The two answer the same on purpose. | Check the slug or id, and which team the token reaches (`GET /v1/me`). | | `409` | It conflicts with the current state: a name already taken, a deployment that can't be cancelled any more, a request with the same `Idempotency-Key` still running. | Read the current state, then decide. | | `422` | Validation failed: `errors` lists each bad field. Also an `Idempotency-Key` reused with a different body. | Fix each field. | | `429` | Over a rate limit. | Wait `Retry-After` seconds. See [Rate limits](https://docs.orbits.africa/api/rate-limits). | | `500` | Something went wrong on Orbits' side. | Retry with backoff and the same `Idempotency-Key`; if it keeps happening, contact support with the `request_id`. | | `502`, `503` | Something the endpoint needs is unreachable for a moment. | Retry shortly, with backoff. | Each operation in the reference lists the errors it can answer, with what each means there. ## Retrying Retry `429`, `500`, `502` and `503`, waiting longer each time (and `Retry-After` on a `429`). Retry a `POST` only with the same `Idempotency-Key` and body, so the change can't happen twice ([Conventions](https://docs.orbits.africa/api/conventions)). Don't repeat any other `4xx` unchanged: it will fail the same way. The SDKs do all of this for you. --- # Rate limits Source: https://docs.orbits.africa/api/rate-limits Limits per person, per API token and per team, the RateLimit headers on every answer, and what to do on a 429. Limits are token buckets: you can make a short burst of requests at once, then they refill at a steady rate. Over a limit, the API answers `429` with `Retry-After` and a problem document, and the request is not carried out. ## The limits | Who | Allowance | Burst | | --- | --- | --- | | Each person, signed in | 1,200 requests a minute | 400 | | Each API token | 300 requests a minute | 100 | | Each team, its members and tokens together | 6,000 requests a minute | | | Sign-in and account routes (`/v1/auth/…`, `/v1/me/…`) and invite lookups, per address | 300 requests a minute | | | Asking for a sign-in email, per address | 30 a minute | | | Sign-in emails to one email address | 5 in a row, then one every three minutes | | A token has a budget of its own, apart from the person who made it, so a busy CI pipeline doesn't slow down that person in the dashboard. Signed-in requests are counted per person and per token, not per address, so many people behind one office network don't affect each other. A team's budget is spent by everyone in it together, so a `429` on a team's route can be the team's budget rather than yours: `RateLimit-Scope: team` says so. An address that keeps sending tokens the API refuses (300 a minute) is made to wait, even when it then sends a good one. ## Headers Every signed-in answer carries your own budget, and every `429` the budget that ran out: | Header | What it says | | --- | --- | | `RateLimit-Limit` | The bucket's size: how many requests can be made at once. | | `RateLimit-Remaining` | Whole requests left in it now. | | `RateLimit-Reset` | Seconds until it is full again. | | `RateLimit-Scope` | Which budget: `user`, `token`, `team`, `address` or `email`. | | `Retry-After` | On a `429` only: whole seconds until one request is allowed. | ```console $ curl -i https://api.theorbits.app/v1/me -H "Authorization: Bearer $ORBITS_TOKEN" HTTP/2 200 ratelimit-limit: 100 ratelimit-remaining: 99 ratelimit-reset: 1 ratelimit-scope: token ``` ## On a 429 Wait `Retry-After` seconds, then send the request again (with the same `Idempotency-Key`, for a `POST` that takes one). Don't retry in a tight loop: every refused request still counts. To stay under the limits, read `RateLimit-Remaining`, poll a deployment every few seconds rather than continuously (or follow its log stream), and use `limit=100` when you read long lists. The CLI and the SDKs wait and retry by themselves. --- # Examples Source: https://docs.orbits.africa/api/examples Whole jobs with the API, step by step in cURL: deploy and wait, roll back, set a variable and redeploy, add a domain, and deploy a folder. Each example uses a `full` token in `ORBITS_TOKEN`, a team `my-team` and a project `my-app`. Replace them with your own. For the same jobs in code, see the [SDKs](https://docs.orbits.africa/sdks); from a terminal, the [CLI](https://docs.orbits.africa/cli) does each in one command. ```console $ export ORBITS_TOKEN=orb_live_… $ export API=https://api.theorbits.app/v1 ``` ## Deploy a branch and wait for it Pushes deploy by themselves. To build a branch's newest commit now: ```console $ curl -X POST "$API/teams/my-team/projects/my-app/deployments" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"branch": "main"}' ``` The answer is `202` with the deployment, `state: "queued"`. The production branch deploys to production; any other branch to a preview. Poll it until its `state` is `ready`, `failed` or `canceled`: ```console $ curl "$API/teams/my-team/projects/my-app/deployments/dpl_…" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Or follow the build log as it happens, as Server-Sent Events: ```console $ curl -N "$API/teams/my-team/projects/my-app/deployments/dpl_…/logs/stream" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` When it is `ready`, its `url` is where it is served. If it `failed`, its `failure` says why, and `GET …/deployments/dpl_…/logs` has the whole log. ## Roll production back List production's deployments, newest first, and pick the one to go back to: ```console $ curl "$API/teams/my-team/projects/my-app/deployments?environment=production" \ -H "Authorization: Bearer $ORBITS_TOKEN" $ curl -X POST "$API/teams/my-team/projects/my-app/deployments/dpl_…/rollback" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Production serves it at once, with no rebuild, and auto-deploy is paused so the next push doesn't replace it. The answer's `undo` is what to send to `POST …/projects/my-app/production` to go back. See [Deployments](https://docs.orbits.africa/api/deployments). ## Set a variable and redeploy ```console $ curl -X POST "$API/teams/my-team/projects/my-app/env" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"variables": [{"key": "STRIPE_SECRET_KEY", "value": "sk_live_…", "environments": ["production"], "sensitive": true}]}' ``` A variable reaches deployments made after it is set. Redeploy production's current deployment to use it: ```console $ curl -X POST "$API/teams/my-team/projects/my-app/deployments/dpl_…/redeploy" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` ## Add a custom domain ```console $ curl -X POST "$API/teams/my-team/domains" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"domain": "shop.example.com", "project": "my-app", "dns": "external"}' ``` The answer's `required_record` is the record to add at your DNS provider. Orbits looks for it every minute; to look now: ```console $ curl -X POST "$API/teams/my-team/domains/shop.example.com/checks" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` When its `state` is `valid`, Orbits issues the certificate and serves the project there. See [Custom domains](https://docs.orbits.africa/domains/custom-domains). ## Deploy a folder A project created with `source_kind: "upload"` deploys from a zip instead of a repository. Start an upload, send the zip to the URL it returns, then complete it: ```console $ curl -X POST "$API/teams/my-team/projects/my-site/uploads" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"size": 482133}' ``` Send the file with the method, URL and headers the answer gives, then `POST …/uploads/{upload}/complete` to deploy it. The zip may be up to 100 MB. The CLI's deploy and the SDKs' upload helpers zip a folder and do all three steps. See [Upload a folder](https://docs.orbits.africa/getting-started/upload-a-folder). --- # OpenAPI and collections Source: https://docs.orbits.africa/api/postman-openapi Download the API's OpenAPI 3.1 contract, or the same requests ready to run in Postman, Insomnia or Bruno. The reference is generated from the API's OpenAPI contract, and so are these downloads. They hold every endpoint an API token can call, and change when the API does. | File | For | | --- | --- | | [orbits-api.yaml](https://docs.orbits.africa/openapi/orbits-api.yaml) | The OpenAPI 3.1 contract, YAML. For code generators, linters, mock servers and AI agents. | | [orbits-api.json](https://docs.orbits.africa/openapi/orbits-api.json) | The same contract as JSON. | | [orbits-api.postman_collection.json](https://docs.orbits.africa/postman/orbits-api.postman_collection.json) | A Postman collection (v2.1): one folder per reference page, each request with its example body. | | [orbits-api.insomnia.json](https://docs.orbits.africa/insomnia/orbits-api.insomnia.json) | An Insomnia export of the same requests. | | [orbits-api.bruno.zip](https://docs.orbits.africa/bruno/orbits-api.bruno.zip) | A Bruno collection: unzip it and open the folder in Bruno. | Operations that are planned and not served yet have "(planned)" at the end of their summary in the contract. ## Postman 1. In Postman, choose **Import** and drop in `orbits-api.postman_collection.json`. 2. Open the collection's **Variables** and set `apiKey` to an API token from **Team › Settings › API tokens**. Put it in **Current value**, which stays on your machine, not **Initial value**, which is shared. 3. Send **Teams and account › Current user** to check the token. The collection sends the token as a bearer token on every request, and a new `Idempotency-Key` on the `POST`s that take one. Slugs and ids in the example URLs (`my-team`, `my-app`, `dpl_…`) are placeholders: replace them with your own. ## Insomnia Import `orbits-api.insomnia.json` (**Import** › **From file**), then set `apiKey` in the collection's base environment. ## Bruno Unzip `orbits-api.bruno.zip` and open the `orbits-api` folder as a collection. Choose the **Production** environment and set its secret `apiKey`. ## Generating a client Most OpenAPI generators read the contract as it is. Before you generate your own, look at the [official SDKs](https://docs.orbits.africa/sdks): they are built from the same contract and add retries, idempotency keys, pagination and waiting for deployments. --- # Using the API from an AI agent Source: https://docs.orbits.africa/api/ai-agents 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](https://docs.orbits.africa/ai/mcp-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](https://docs.orbits.africa/ai/connect-your-ai). ## Build your own agent on an SDK Writing the agent yourself? The [SDKs](https://docs.orbits.africa/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. ## Give it one link The [agent brief](https://docs.orbits.africa/agent-brief.md) 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](https://docs.orbits.africa/openapi/orbits-api.yaml) too, and the whole site is in [/llms.txt](https://docs.orbits.africa/llms.txt) and [/llms-full.txt](https://docs.orbits.africa/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](https://docs.orbits.africa/api/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 `POST`s that take one, and the same key when retrying ([Conventions](https://docs.orbits.africa/api/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](https://docs.orbits.africa/api/errors)). --- # Projects Source: https://docs.orbits.africa/api/projects Create, read, change, pause and delete projects, and list the starter templates. A project is one app: its source (a Git repository, or uploads), how it builds, and its addresses. Its `slug` is unique across Orbits, because it is the free address `.theorbits.app`; renaming a project changes it. `{project}` in a path is the slug or the `prj_` id. See [Projects](https://docs.orbits.africa/deploy/projects) for the guide. Endpoints: - `GET /v1/templates`: Starter templates for a new project - `GET /v1/teams/{team}/projects`: List projects - `POST /v1/teams/{team}/projects`: Create a project from a repository or a template - `GET /v1/teams/{team}/projects/{project}`: Get a project - `PATCH /v1/teams/{team}/projects/{project}`: Change project settings - `DELETE /v1/teams/{team}/projects/{project}`: Delete a project - `GET /v1/teams/{team}/projects/{project}/deletion-impact`: What deleting a project removes - `POST /v1/teams/{team}/projects/{project}/pause`: Pause or resume a project ## The project object - `id` (string, required) - `slug` (string, required) - `name` (string, required) - `free_address` (string, required): Host name, `.theorbits.app`. - `workload` (Workload, required) - `type` (string, required): Always `container`. - `output_directory` (string) - `spa_fallback` (boolean): Defaults to `false`. - `framework` (string) - `memory_mb` (integer): At least 128. - `timeout_seconds` (integer): At least 1. - `command` (array of string) - `replicas` (integer): At least 1. Defaults to `1`. - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker. - `port` (integer): From 1 to 65535. - `health_check_path` (string): Defaults to `/`. - `start_command` (array of string) - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`. - `dockerfile_path` (string or null) - `source` (null or Source) - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`. - `repository` (string, required) - `production_branch` (string, required): Defaults to `main`. - `root_directory` (string): Defaults to `./`. - `source_kind` (string): `upload`: deployed by dropping files (`POST .../uploads`); `source` is null and there is no repository. One of `git`, `upload`. Defaults to `git`. - `build` (BuildConfig) - `framework` (string or null) - `install_command` (string or null): null means detected default. - `build_command` (string or null) - `output_directory` (string or null) - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`. - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday"). - `id` (string) - `name` (string) - `changed_at` (string or null) - `framework_version` (string or null): Shown next to the framework on the overview header, e.g. `15`. - `node_version` (string) - `region` (string, required) - `status` (string, required): What the project cards and the project switcher show. `pending` means nothing has been deployed yet. `building`, `ready` and `failed` follow the latest deployment (a canceled latest one falls back to production: `ready`, or `pending` if nothing served yet). One of `pending`, `building`, `ready`, `failed`, `paused`. - `paused` (boolean) - `git` (GitSettings, required) - `deploy_on_push` (boolean, required): Pushes to the production branch go to production; other branches get a preview. - `preview_pull_requests` (boolean, required): Each pull request gets its own address. - `comment_on_pull_requests` (boolean, required): Post the preview link on the pull request and update it on every push. - `preview_protection` (string): Who may open previews (production stays public). `password`: the edge asks for the project's preview password and remembers it for 12 hours. One of `none`, `team_members`, `password`. Defaults to `team_members`. - `production_url` (string or null) - `latest_deployment_id` (string or null) - `latest_deployment` (null or LatestDeployment) - `id` (string, required) - `state` (string, required): `queued` waits for a builder; the screens show it as building. One of `queued`, `building`, `ready`, `failed`, `canceled`. - `branch` (string or null) - `commit_sha` (string or null) - `commit_message` (string or null) - `author` (object or null) - `name` (string) - `avatar_url` (string or null) - `failure_reason` (string or null) - `created_at` (string, required) - `thumbnail_url` (string or null): API path of the screenshot of what production serves, for the project card (the `screenshot_url` of that deployment). Null until production has one. Fetch it with the session, like any API call. - `thumbnail_color` (string or null): The screenshot's most common strong colour, which the project card glows in. Null without a screenshot, or when the page is all black, white and grey. - `created_at` (string, required) - `updated_at` (string) ## Starter templates for a new project ```http GET /v1/templates ``` The "Start from a template" catalog on the New project screens, read from [the-orbits/templates](https://github.com/the-orbits/templates) (its `catalog.json`, cached for five minutes). A template added there appears here without a backend change. `workload` and `node_version`, when present, are what a project created from the template gets; `optional_env` lists variables the template reads when they are set. If the templates repository cannot be reached and nothing is cached, the list built into the service is served instead. **Permissions:** Any signed-in user. Token: any API token (`read` or `full`). Example: ```sh curl "https://api.theorbits.app/v1/templates" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "key": "store", "name": "Store", "description": "Product pages, cart, checkout", "category": "commerce", "framework": "nextjs", "framework_label": "Next.js", "required_env": [ { "key": "PAYSTACK_SECRET_KEY", "hint": "From Paystack, Settings → API Keys." } ], "optional_env": [ { "key": "PAYSTACK_SECRET_KEY", "hint": "From Paystack, Settings → API Keys." } ], "workload": { "type": "app", "port": 3000, "health_check_path": "/health" }, "node_version": "24.x" } ] } ``` Errors: ## List projects ```http GET /v1/teams/{team}/projects ``` The projects of a team, for the project cards on the team overview and for the project switcher. Fields that come from deployments (`status`, `latest_deployment`, `thumbnail_url`) are `pending` or null until the deployment pipeline exists. Paused projects report `status: paused`. Sorting: `last_deploy` (default) puts the most recently deployed first, then projects with no deployment by `created_at`. An API token limited to one project may call this too: the list then holds only that project (still subject to `q` and `repository`), with `next_cursor: null`. **Permissions:** Any team member, including viewers. A non-member gets 404, the same as an unknown team. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string) - `q` (string) - `sort` (string): One of `last_deploy`, `name`, `created`. Defaults to `last_deploy`. - `repository` (string): Only projects imported from this repository, e.g. `shadyventures/storefront`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "next_cursor": null, "items": [ { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "state": "queued", "branch": null, "commit_sha": null, "commit_message": "Update checkout copy", "author": { "name": "my-app", "avatar_url": "https://my-app.theorbits.app" }, "failure_reason": "Missing module 'mdsvex'", "created_at": "2026-11-10T09:30:00Z" }, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Create a project from a repository or a template ```http POST /v1/teams/{team}/projects ``` Create a project: the Deploy button on the New project > Configure screens. `name` becomes the free address, `.theorbits.app`, where `slug` is the name in lower case with hyphens (or the `slug` you send). It must be unique across all teams: 409 means ask for another name. `workload` is optional. When omitted it is derived from `build.framework`: `nextjs`, `sveltekit`, `nuxt`, `remix`, `reactrouter`, `solidstart` and `tanstack-start` become a `function`, `node`, `elysia` and `dolphjs` an `app`, and everything else `static`. For a GitHub `source`, Orbits asks the Git service whether the team's GitHub connection can see the repository. 422 with `source.repository` means it cannot (not found, or not installed on that repository); 422 with `source.provider` means GitHub is not connected to the team. If that check cannot be completed the answer is 503 and nothing is created; retry. With a `template` instead, Orbits creates a private repository named after the project's slug in the team's connected GitHub account, commits the template's files into it, and creates the project from it with the template's `workload` and `node_version`; the first deployment is queued as for an import. Every variable in the template's `required_env` must be sent in `env` (422 on `env` otherwise), and the address must be free before the repository is created. In a personal GitHub account the caller must have approved Orbits first (`GET /v1/teams/{team}/integrations/github/approval`). 409 covers a taken address, a repository of that name already in the account, GitHub not connected, a personal account not yet approved, and an organisation whose installation has not yet accepted the Orbits app's Administration and Contents permissions; its `detail` says which. 503 means GitHub could not be reached. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. Body: - `name` (string, required): Also the source of the slug and free address, e.g. `checkout-v2`. At most 100 characters. - `slug` (string) - `workload` (Workload) - `type` (string, required): Always `container`. - `output_directory` (string) - `spa_fallback` (boolean): Defaults to `false`. - `framework` (string) - `memory_mb` (integer): At least 128. - `timeout_seconds` (integer): At least 1. - `command` (array of string) - `replicas` (integer): At least 1. Defaults to `1`. - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker. - `port` (integer): From 1 to 65535. - `health_check_path` (string): Defaults to `/`. - `start_command` (array of string) - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`. - `dockerfile_path` (string or null) - `source` (Source) - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`. - `repository` (string, required) - `production_branch` (string, required): Defaults to `main`. - `root_directory` (string): Defaults to `./`. - `template` (string): Template `key` from `GET /v1/templates`. Mutually exclusive with `source`: Orbits creates the repository in the team's GitHub account. - `source_kind` (string): Default `git`. `upload` creates a project with no repository, deployed by dropping files (`POST /teams/{team}/projects/{project}/uploads`); no deployment is queued until the first drop. Not with `source` or `template`. One of `git`, `upload`. - `build` (BuildConfig) - `framework` (string or null) - `install_command` (string or null): null means detected default. - `build_command` (string or null) - `output_directory` (string or null) - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`. - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday"). - `id` (string) - `name` (string) - `changed_at` (string or null) - `region` (string): Defaults to `abj-1`. - `env` (array of object): Environment variables from the Configure step (Used by Production and Preview). They are saved with the project in one step; field errors come back as `env[0].key`. At most 500 items. - `key` (string, required): At most 255 characters. - `value` (string, required): May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on `EnvVar.value`. At most 32768 characters. - `environments` (array of string): Used by Production and Preview unless the user picks otherwise. - `sensitive` (boolean): Write-only: nobody can read the value back, only replace it. Defaults to `true`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app" }' ``` Response `202`: ```json { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "state": "queued", "branch": null, "commit_sha": null, "commit_message": "Update checkout copy", "author": { "name": "my-app", "avatar_url": "https://my-app.theorbits.app" }, "failure_reason": "Missing module 'mdsvex'", "created_at": "2026-11-10T09:30:00Z" }, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: The repository could not be verified, or GitHub could not be reached to create one; nothing was created. Retry. ## Get a project ```http GET /v1/teams/{team}/projects/{project} ``` One project, for the project overview header and for the Settings form. **Permissions:** Any team member. A non-member, or a project in another team, gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "state": "queued", "branch": null, "commit_sha": null, "commit_message": "Update checkout copy", "author": { "name": "my-app", "avatar_url": "https://my-app.theorbits.app" }, "failure_reason": "Missing module 'mdsvex'", "created_at": "2026-11-10T09:30:00Z" }, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Change project settings ```http PATCH /v1/teams/{team}/projects/{project} ``` Change project settings. Settings save as the user makes them (the Settings screen shows "All changes saved"), so send only the fields that changed. Changes apply from the next deployment; existing deployments keep the snapshot taken when they were built. Renaming (`name`) also changes `slug` and the free address. The workload type cannot change after creation (422). `build` and `git` are merged field by field: omit a field to keep it, send `null` in `build` to go back to the detected default. `preview_password` is write-only and only valid with `preview_protection: password`. **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `name` (string): At most 100 characters. - `workload` (Workload) - `type` (string, required): Always `container`. - `output_directory` (string) - `spa_fallback` (boolean): Defaults to `false`. - `framework` (string) - `memory_mb` (integer): At least 128. - `timeout_seconds` (integer): At least 1. - `command` (array of string) - `replicas` (integer): At least 1. Defaults to `1`. - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker. - `port` (integer): From 1 to 65535. - `health_check_path` (string): Defaults to `/`. - `start_command` (array of string) - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`. - `dockerfile_path` (string or null) - `source` (Source) - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`. - `repository` (string, required) - `production_branch` (string, required): Defaults to `main`. - `root_directory` (string): Defaults to `./`. - `build` (BuildConfig) - `framework` (string or null) - `install_command` (string or null): null means detected default. - `build_command` (string or null) - `output_directory` (string or null) - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`. - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday"). - `id` (string) - `name` (string) - `changed_at` (string or null) - `git` (object) - `deploy_on_push` (boolean) - `preview_pull_requests` (boolean) - `comment_on_pull_requests` (boolean) - `node_version` (string) - `preview_protection` (string): One of `none`, `team_members`, `password`. - `preview_password` (string): Only with `preview_protection` `password`. - `region` (string) Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "node_version": "22.x", "preview_protection": "none", "preview_password": "preview-password", "region": "region" }' ``` Response `200`: ```json { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "state": "queued", "branch": null, "commit_sha": null, "commit_message": "Update checkout copy", "author": { "name": "my-app", "avatar_url": "https://my-app.theorbits.app" }, "failure_reason": "Missing module 'mdsvex'", "created_at": "2026-11-10T09:30:00Z" }, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Delete a project ```http DELETE /v1/teams/{team}/projects/{project} ``` Delete a project (Settings > Delete project). The record is removed and an Operation is returned; downstream cleanup will be tracked by the same Operation once those services exist. **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `202`: ```json { "id": "op_01jc8x6e4mq2v7r9y3t5b0zp8w", "kind": "team.delete", "state": "pending", "resource": "resource", "created_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "error": { "type": "https://my-app.theorbits.app", "title": "title", "status": 1, "detail": "detail", "instance": "instance", "request_id": "request-id", "code": "code", "required_plan": "pro", "feature": "functions", "errors": [ { "field": "field", "message": "message" } ] } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## What deleting a project removes ```http GET /v1/teams/{team}/projects/{project}/deletion-impact ``` The numbers on the Delete modal: "126 deployments and their build logs, 11 environment variables, 5 flags and their history, 4 domains are detached". **Permissions:** Owner or admin, like the delete itself. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deletion-impact" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "deployments": 1, "environment_variables": 1, "flags": 1, "domains": 1 } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Pause or resume a project ```http POST /v1/teams/{team}/projects/{project}/pause ``` Pause or resume a project (the Paused toggle in Settings > Advanced). While paused, its production, preview and custom-domain addresses answer 503 with Orbits' paused page, its apps stop, and nothing deploys; domains, data and the builds production can come back to stay. Resuming serves production again within moments. The response is the updated Project (`paused` and `status: paused`), not an Operation: the toggle needs an immediate answer, and the runtime effect is reported through `status`. **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `paused` (boolean, required) Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/pause" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "paused": false }' ``` Response `200`: ```json { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": { "type": "static", "output_directory": "dist", "spa_fallback": false }, "source": { "provider": "github", "repository": "shadyventures/storefront", "production_branch": "main", "root_directory": "./" }, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": { "id": "id", "name": "my-app" }, "changed_at": "2026-11-10T09:30:00Z" }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": false, "preview_pull_requests": false, "comment_on_pull_requests": false }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "state": "queued", "branch": null, "commit_sha": null, "commit_message": "Update checkout copy", "author": { "name": "my-app", "avatar_url": "https://my-app.theorbits.app" }, "failure_reason": "Missing module 'mdsvex'", "created_at": "2026-11-10T09:30:00Z" }, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Deployments Source: https://docs.orbits.africa/api/deployments Start, follow, promote, roll back, redeploy and cancel deployments, upload source, and read build logs. A deployment is one build of a project, immutable once built. A push to a connected repository creates one by itself; `POST .../deployments` builds a branch's newest commit, and a project with `source_kind: upload` deploys from a zip you upload. Creating one answers `202` with the new deployment: poll it, or follow its build log stream, until its `state` is `ready`, `failed` or `canceled`. Promoting, rolling back and setting production move a pointer. See [Deployments](https://docs.orbits.africa/deploy/deployments). Endpoints: - `GET /v1/teams/{team}/deployments`: Deployments across the team's projects - `GET /v1/teams/{team}/projects/{project}/deployments`: A project's deployments - `POST /v1/teams/{team}/projects/{project}/deployments`: Deploy a branch now - `POST /v1/teams/{team}/projects/{project}/uploads`: Start dropping a site or app - `POST /v1/teams/{team}/projects/{project}/uploads/{upload}/complete`: Deploy a dropped archive - `DELETE /v1/teams/{team}/projects/{project}/uploads/{upload}`: Cancel a drop - `POST /v1/teams/{team}/projects/{project}/production`: Set what production serves - `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}`: A deployment and its build steps - `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs`: Build log lines - `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs/stream`: Follow a build live (server-sent events) - `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot`: A deployment's screenshot - `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/redeploy`: Build the same commit again - `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/promote`: Promote to production - `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/rollback`: Roll production back - `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/cancel`: Cancel a build ## The deployment object - `id` (string, required) - `project` (DeploymentProject, required) - `id` (string, required) - `slug` (string, required) - `name` (string, required) - `environment` (string, required): Where a deployment runs. `development` is only the local `orbits dev` target and an environment-variable scope. One of `production`, `preview`. - `state` (string, required): `queued` waits for a builder; the screens show it as building. One of `queued`, `building`, `ready`, `failed`, `canceled`. - `trigger` (string, required): `git` a push, `manual` deployed by hand, `redeploy`, `promote`, `create` the first deploy of a new project. One of `git`, `manual`, `redeploy`, `promote`, `create`. - `branch` (string, required) - `sha` (string or null, required): The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters. - `message` (string or null, required): The commit message's first line. - `author` (null or object, required) - `name` (string, required) - `created_by` (null or object, required): Who asked for it; null for a push. - `id` (string, required) - `name` (string, required) - `url` (string or null, required): This deployment's own address, `https://-.`; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch. - `current` (boolean, required): Production serves it now. - `went_live` (boolean, required): Production served it at some point. - `redeploy_of` (string or null, required): The commit sha a redeploy rebuilt. - `promoted_from` (string or null, required): The `dpl_` id of the deployment a promote rebuilt. - `pull_request` (integer or null, required): The open pull request of the branch, for a preview. - `use_cache` (boolean, required) - `created_at` (string, required) - `started_at` (string or null, required) - `finished_at` (string or null, required) - `duration_seconds` (integer or null, required): From start to finish; null while it runs (count up from `started_at`). - `screenshot_url` (string or null, required): API path of the deployment's first screen (1280x800 JPEG), `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot`. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one. - `warnings` (array of DeploymentWarning, required): What this deployment may be missing, for its page; empty when nothing is. `missing_env`: public variables the code reads (`import.meta.env.VITE_*`, `process.env.NEXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`) that weren't set for this environment, nor in a committed `.env` or `.env.production`, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. `page`: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank. - `kind` (string, required): One of `missing_env`, `page`. - `message` (string, required) - `keys` (array of string): `missing_env`: the variable names, sorted. - `errors` (array of string): `page`: the uncaught errors, first three. - `blank` (boolean): `page`: the first screen had nothing on it. ## Deployments across the team's projects ```http GET /v1/teams/{team}/deployments ``` The team's Deployments page: every deployment across its projects, newest first, with the facets for its filters (Project, Environment, Status, Author) and "38 this week". An API token limited to one project may call this too: the deployments, `projects`, `authors`, `total` and `this_week` then cover only that project, and a `project` filter naming another project returns an empty list. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string) - `q` (string): Matches the commit message, branch, sha or author. - `project` (string): Project slug or `prj_` id. - `environment` (string): One of `production`, `preview`. - `state` (string): One of `queued`, `building`, `ready`, `failed`, `canceled`. - `author` (string): An `authors[].name`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/deployments" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ], "total": 1, "this_week": 1, "projects": [ { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" } ], "authors": [ { "name": "My Team" } ], "next_cursor": null } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## A project's deployments ```http GET /v1/teams/{team}/projects/{project}/deployments ``` The project's Deployments page: every build, newest first, with the filters (search, Env, Status, Branch, "Production only") and what the inspector shows when nothing is picked (`current`, the deployment production serves, and its `domains`). **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string) - `q` (string): Matches the commit message, branch, sha or author. - `environment` (string): One of `production`, `preview`. - `state` (string): One of `queued`, `building`, `ready`, `failed`, `canceled`. - `branch` (string) - `live` (boolean): Only deployments that have served production. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ], "total": 1, "all": 1, "branches": [ "branches" ], "current": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] }, "auto_deploy_paused": false, "domains": [ { "name": "storefront.theorbits.app", "state": "valid", "custom": false } ], "building": false, "next_cursor": null } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Deploy a branch now ```http POST /v1/teams/{team}/projects/{project}/deployments ``` Queues a build of a branch's newest commit, for a deploy started by hand (the CLI's `orbits deploy`). The production branch deploys to production; any other branch to preview. Pushes and the first deploy of a new project are queued by Orbits itself and need no call. Returns at once with the queued deployment; follow it with `GET .../deployments/{deployment}` and its logs. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `branch` (string): At most 255 characters. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "branch": "main" }' ``` Response `202`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Start dropping a site or app ```http POST /v1/teams/{team}/projects/{project}/uploads ``` The drag and drop deploy: the person drops a folder (or a `.zip`) on the project, and the browser sends it to storage on a presigned URL, so the files never pass through the API. The archive is the project's **source code**, in place of a Git clone: Orbits unpacks it, detects the framework, installs, builds and publishes or runs it like any other deployment, for any kind of project. Only projects created with `source_kind: upload` take drops. What goes in the archive: the project's files, with `package.json`, source and config. Anything named `node_modules`, `.git`, `.next`, `__MACOSX` or `.DS_Store`, at any depth, is left out, and a single top-level folder is stripped, so zipping the folder or its contents both work. Limits: the zip may be up to `max_bytes` (100 MiB, 104,857,600 bytes); unpacked it may be up to 500 MiB and 20,000 entries, where the folders the zip lists count as well as its files (what is left out doesn't count); links and special files are refused. The build reports a breach on the Cloning step. Starting signs a PUT URL for the zip (valid ten minutes). At most 5 unfinished uploads per team. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `size` (integer, required): The zip's size in bytes. The URL accepts a file of exactly this length. From 1 to 104857600. - `filename` (string): Shown as the deployment's message, e.g. `Uploaded site.zip`. At most 255 characters. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "size": 1 }' ``` Response `201`: ```json { "id": "upl_0192f3a6-0c1d-7a55-9a52-6f1f0f0f0f0f", "method": "PUT", "url": "https://my-app.theorbits.app", "headers": {}, "expires_at": "2026-11-10T09:30:00Z", "max_bytes": 1 } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: `not_an_upload_project` (the project deploys from Git) or `too_many_uploads` (finish or cancel the others). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Deploy a dropped archive ```http POST /v1/teams/{team}/projects/{project}/uploads/{upload}/complete ``` Say the browser has sent the zip. Orbits checks that it arrived whole and is a zip, then queues a production deployment that builds it (`trigger: manual`, the message is `Uploaded `). Returns at once; follow the deployment and its logs as for any build. The archive is kept, with the project's four previous ones, so Redeploy can rebuild it. If the file hasn't arrived yet this is 409 `upload_incomplete`: wait a second and call again. Completing an upload twice returns the same deployment. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `upload`: The `id` from `POST .../uploads`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads/upl_01jc8x6e4mq2v7r9y3t5b0zp8w/complete" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `202`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: `upload_incomplete` (not arrived yet) or `upload_expired` (start again). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Cancel a drop ```http DELETE /v1/teams/{team}/projects/{project}/uploads/{upload} ``` Abandons an upload that was started and not completed; the file, if it arrived, is removed. Cancelling one that is gone or already completed is a no-op (the deployment it made is unaffected). Not needed for an upload that simply expires. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `upload`: The `id` from `POST .../uploads`. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads/upl_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Cancelled. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Set what production serves ```http POST /v1/teams/{team}/projects/{project}/production ``` Points production at a deployment that served production before, and sets whether pushes may replace it. It is the Undo of a rollback (send back the rollback answer's `undo`), and with the current deployment and `auto_deploy_paused: false` it lifts a rollback's pause. No rebuild. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `deployment_id` (string, required) - `auto_deploy_paused` (boolean, required) Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/production" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "auto_deploy_paused": false }' ``` Response `200`: ```json { "deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] }, "auto_deploy_paused": false } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## A deployment and its build steps ```http GET /v1/teams/{team}/projects/{project}/deployments/{deployment} ``` The deployment page and the inspector: the header, the details grid (status, environment, duration, created, branch, commit, region, framework), production's domains when it is the current deployment, the six build steps with their state and seconds, and why a failed build stopped. The log lines themselves come from `GET .../logs`. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ], "framework": "Next.js 16", "region": "abj-1", "domains": [ { "name": "storefront.theorbits.app", "state": "valid", "custom": false } ], "steps": [ { "key": "queued", "state": "pending", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": null } ], "failure": { "title": "Type error in lib/cart.ts, line 42", "message": "Property 'total' does not exist on type 'Cart'.", "step": "queued", "line": null }, "log_lines": 1, "open_graph": { "title": "Fifteen Seconds", "description": null, "image": "https://fifteen-seconds-85234cf.theorbits.app/og.png", "image_was_relative": false, "url": "https://my-app.theorbits.app", "site_name": null, "twitter_card": "summary_large_image", "twitter_title": null, "twitter_description": null, "twitter_image": "https://my-app.theorbits.app", "favicon": "https://my-app.theorbits.app", "fetched_at": "2026-11-10T09:30:00Z" } } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Build log lines ```http GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs ``` The build log, oldest line first. Each line names its step, so the deployment page can group lines under Queued, Cloning repository, Installing packages, Building, Uploading and Going live. A build keeps at most 5000 lines. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Query parameters: - `after` (integer): Return lines after this `n`. At least 0. Defaults to `0`. - `limit` (integer): From 1 to 2000. Defaults to `500`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "n": 1, "at": "2026-11-10T09:30:00Z", "step": "queued", "tone": "plain", "text": "text" } ], "next_after": 1, "done": false } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Follow a build live (server-sent events) ```http GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs/stream ``` The live build log, pushed as server-sent events (`text/event-stream`), for New project · Deploying, a building deployment and Follow output. Lines arrive under a second after the build prints them. Events: - `line` (its `id` is the line's `n`): `{"n", "at", "step", "tone", "text"}`, oldest first. - `steps`: the six steps, as in the deployment's `steps`, whenever one changes. - `done`: `{"state", "failure", "duration_seconds"}` once the build has ended and every line has been sent. The stream then closes, unless the deployment just went ready. - `screenshot`: `{"screenshot_url"}`, the same URL the deployment's `screenshot_url` gives. The builder takes the screenshot a few seconds after the deployment is ready, so after `done` the stream stays open for up to 2 minutes and sends this when it is saved, then closes. Refresh the deployment (or its thumbnail) on it. It is not sent for a failed or canceled build, a worker, a deployment that already had its screenshot, or one that finished more than 2 minutes ago. - A `: keep-alive` comment every 15 s while nothing happens. The stream closes after 30 minutes or when a proxy cuts it (staging's after 5); reconnect with `Last-Event-ID` set to the last line `id` received (EventSource does this by itself) and it carries on with the next line, without gaps or repeats. A finished deployment answers with any remaining lines, its steps and `done` at once. **Permissions:** Any team member. A non-member gets 404 (a problem document, not a stream). Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Query parameters: - `after` (integer): The same as Last-Event-ID, for a first connection that already has lines. At least 0. Defaults to `0`. Example: ```sh curl -N "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs/stream" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200` (text/event-stream): The event stream. Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## A deployment's screenshot ```http GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot ``` The image for the deployment inspector, the deployment page, New project's Preview box and the project card: the first screen (1280x800) of the deployment's home page, as a JPEG, taken by the builder a few seconds after the deployment became ready. It never changes once taken, so it is sent with `Cache-Control: private, max-age=604800, immutable`. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/screenshot" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -o screenshot.jpg ``` Response `200` (image/jpeg): The JPEG. Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Build the same commit again ```http POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/redeploy ``` The Redeploy modal: builds this deployment's commit again in the same environment, as a new deployment. A production redeploy takes over production when it is ready; until then production keeps serving the current build. A deployment that failed before its commit was known rebuilds its branch's newest commit. A dropped upload is rebuilt from its stored archive; only the project's last 5 are kept, and an older one is 409 `source_expired` (drop the site again). **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Body: - `use_cache` (boolean): Defaults to `true`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/redeploy" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "use_cache": true }' ``` Response `202`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Promote to production ```http POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/promote ``` The Promote modal: rebuilds a ready deployment's commit with production's environment variables, as a new production deployment that goes live when it is ready. The current version stays live until then. Promoting also lifts a rollback's pause on auto-deploy. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/promote" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `202`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Roll production back ```http POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/rollback ``` Points production at an earlier production build straight away, with no rebuild, and pauses auto-deploy so the next push does not replace it (pushes still build; they just do not go live). The answer's `undo` restores what production served before, through `POST .../projects/{project}/production`. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/rollback" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "deployment": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] }, "auto_deploy_paused": false, "undo": { "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "auto_deploy_paused": false } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Cancel a build ```http POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/cancel ``` "Cancel deployment": a queued deployment is canceled at once; a building one is stopped by its builder within a few seconds (the answer still says `building`; poll until it says `canceled`). Nothing it built goes live. **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `deployment` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/cancel" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `202`: ```json { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "environment": "production", "state": "queued", "trigger": "git", "branch": "main", "sha": null, "message": "Update checkout copy", "author": { "name": "Shady Asaolu" }, "created_by": { "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "url": "https://storefront-a1f9c2e.theorbits.app", "current": false, "went_live": false, "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "pull_request": null, "use_cache": false, "created_at": "2026-11-10T09:30:00Z", "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "duration_seconds": null, "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot", "warnings": [ { "kind": "missing_env", "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.", "keys": [ "keys" ], "errors": [ "errors" ], "blank": false } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. --- # Environment variables Source: https://docs.orbits.africa/api/environment-variables A project's variables per environment: list, add, change, delete and restore them, reveal one, or pull them all. Each variable is a key with a value for one or more environments (`production`, `preview`, `development`). Values are encrypted at rest and never returned by a list: reveal one, or pull an environment's, with a `full` token. A `read` token never reads values. A change applies to deployments created after it: redeploy to use it. See [Environment variables](https://docs.orbits.africa/deploy/environment-variables). Endpoints: - `GET /v1/teams/{team}/projects/{project}/env`: List variables - `POST /v1/teams/{team}/projects/{project}/env`: Add variables, or import a .env file - `PATCH /v1/teams/{team}/projects/{project}/env/{key}`: Change a value or its environments - `DELETE /v1/teams/{team}/projects/{project}/env/{key}`: Delete a variable - `POST /v1/teams/{team}/projects/{project}/env/{key}/restore`: Undo a delete - `POST /v1/teams/{team}/projects/{project}/env/{key}/reveal`: Reveal a value - `POST /v1/teams/{team}/projects/{project}/env/pull`: Download values for local development (`orbits env pull`) ## The environment variable object - `id` (string, required) - `key` (string, required) - `value` (string or null, required): Only for a non-sensitive variable whose key is meant for the browser (`NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`, `REACT_APP_`, `EXPO_PUBLIC_` prefix, or a `_PUBLIC_KEY` suffix). Otherwise null; use `POST .../env/{key}/reveal`. - `sensitive` (boolean, required) - `environments` (array of string, required) - `pending_redeploy` (boolean, required): Changed since the latest deployment; shows the "New" tag. - `created_at` (string, required) - `updated_at` (string, required) - `updated_by` (object, required) - `id` (string, required) - `name` (string, required) ## List variables ```http GET /v1/teams/{team}/projects/{project}/env ``` The Environment variables page: one row per `key`, with the environments it applies to. Values are encrypted at rest. A row's `value` is returned only for a variable that is not `sensitive` and whose key is meant for the browser (it starts with `NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`, `REACT_APP_` or `EXPO_PUBLIC_`, or ends with `_PUBLIC_KEY`); every other `value` is `null` and the page shows dots. A `sensitive` variable can never be read back by anyone (the dialog says "Nobody can read it back, only replace it"), so show no eye icon, Reveal value or Copy value for it. For any other variable, "Reveal value" and "Copy value" call `POST /v1/teams/{team}/projects/{project}/env/{key}/reveal`. `total` is the number of variables that match the filters ("10 variables"). `last_changed` feeds the pull dialog ("Last changed yesterday by Shady Asaolu"); it is `null` when there are none. `redeploy` drives the blue banner ("You changed 1 variable. Redeploy so production picks it up."): `required` is true when something changed since the project's latest deployment and `changed` counts those variables; each row's `pending_redeploy` marks the ones to highlight (the "New" tag). Until deployments exist, `redeploy.required` is always false. **Permissions:** Any team member, including viewers. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string) - `environment` (string): Only variables that apply to this environment. One of `production`, `preview`, `development`. - `q` (string): Substring of the key. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "next_cursor": null, "items": [ { "id": "var_01J9ZK3Q", "key": "key", "value": null, "sensitive": false, "environments": [ "production" ], "pending_redeploy": false, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z", "updated_by": { "id": "id", "name": "my-app" } } ], "total": 1, "last_changed": { "at": "2026-11-10T09:30:00Z", "by": { "id": "id", "name": "my-app" } }, "redeploy": { "required": false, "changed": 1 } } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Add variables, or import a .env file ```http POST /v1/teams/{team}/projects/{project}/env ``` Saves one or more variables. The Add variable dialog sends one with the default `on_conflict: fail`: a key that already exists is 409 and nothing is saved (use Edit instead). The Import .env dialog sends every parsed line with `on_conflict: replace`, which replaces the value and environments of keys that already exist, as its warning says ("Importing replaces its value in the environments you pick"). The dialog parses the file in the browser; show the conflicts from the list you already loaded. `sensitive` defaults to true, as the Sensitive checkbox does. A project can have at most 1,000 variables. An import that would go over (replacing existing keys adds none) is 422 on `variables` and saves nothing. The request body is at most 1 MiB, which the gateway enforces on every request (413), so a very large import must be split. The new values apply to deployments created afterwards; `redeploy_required` says whether the banner should show. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `variables` (array of object, required): At most 500 items. - `key` (string, required): At most 255 characters. - `value` (string, required): May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on `EnvVar.value`. At most 32768 characters. - `environments` (array of string): Used by Production and Preview unless the user picks otherwise. - `sensitive` (boolean): Write-only: nobody can read the value back, only replace it. Defaults to `true`. - `on_conflict` (string): `fail` (Add variable): a key that already exists is 409 and nothing is saved. `replace` (Import .env): existing keys get the new value and environments. One of `fail`, `replace`. Defaults to `fail`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "variables": [ { "key": "STRIPE_SECRET_KEY", "value": "value", "environments": [ "production" ], "sensitive": true } ] }' ``` Response `201`: ```json { "items": [ { "id": "var_01J9ZK3Q", "key": "key", "value": null, "sensitive": false, "environments": [ "production" ], "pending_redeploy": false, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z", "updated_by": { "id": "id", "name": "my-app" } } ], "created": 1, "replaced": 1, "redeploy_required": false } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Change a value or its environments ```http PATCH /v1/teams/{team}/projects/{project}/env/{key} ``` The Edit dialog: the key is read-only ("To rename a key, add a new one and delete this one"). Send `value` only when the user typed a new one; leave it out to change just the environments. Send `environments` only when the checkboxes changed. At least one of them is required. Whether a variable is `sensitive` cannot be changed here. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `key` Body: - `value` (string): At most 32768 characters. - `environments` (array of string) Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "value": "value", "environments": [ "production" ] }' ``` Response `200`: ```json { "item": { "id": "var_01J9ZK3Q", "key": "key", "value": null, "sensitive": false, "environments": [ "production" ], "pending_redeploy": false, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z", "updated_by": { "id": "id", "name": "my-app" } }, "redeploy_required": false } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Delete a variable ```http DELETE /v1/teams/{team}/projects/{project}/env/{key} ``` The Delete dialog ("Type STRIPE_SECRET_KEY to confirm"; the typed confirmation is checked in the browser). The variable is hidden at once but its encrypted value is kept until `restorable_until` (10 minutes), so the toast's Undo can call `POST /v1/teams/{team}/projects/{project}/env/{key}/restore`. Deployments created after the delete no longer get it. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `key` Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "key": "key", "restorable_until": "2026-11-10T09:30:00Z", "redeploy_required": false } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Undo a delete ```http POST /v1/teams/{team}/projects/{project}/env/{key}/restore ``` The Undo button on the "deleted" toast. It brings the variable back with the value and environments it had. 404 means the 10 minutes have passed (or it was never deleted); 409 means a variable with that key exists again. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `key` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/restore" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "item": { "id": "var_01J9ZK3Q", "key": "key", "value": null, "sensitive": false, "environments": [ "production" ], "pending_redeploy": false, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z", "updated_by": { "id": "id", "name": "my-app" } }, "redeploy_required": false } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Reveal a value ```http POST /v1/teams/{team}/projects/{project}/env/{key}/reveal ``` "Reveal value" and "Copy value" (and the eye icon) on a row. It is a POST because every reveal is recorded as a `project.env.revealed` event with who asked and which key, never the value. A `sensitive` variable answers 409: it can never be read back. The response is never cached or replayed: this call ignores `Idempotency-Key`, so every call reads the value again and is recorded. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `key` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/DATABASE_URL/reveal" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "key": "key", "value": "value" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Download values for local development (`orbits env pull`) ```http POST /v1/teams/{team}/projects/{project}/env/pull ``` What `orbits env pull` calls to write `.env.local`. It returns the values of every variable that applies to `environment`, except `sensitive` ones, which nobody can read back: their keys are listed in `skipped_sensitive` so the CLI can tell the user. Every pull is recorded as a `project.env.pulled` event. The response is never cached or replayed: this call ignores `Idempotency-Key`, so every call reads the values again and is recorded. The dashboard only shows the pull dialog; it does not call this endpoint. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `environment` (string, required): One of `production`, `preview`, `development`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/env/pull" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "environment": "production" }' ``` Response `200`: ```json { "environment": "production", "variables": {}, "skipped_sensitive": [ "skipped-sensitive" ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. --- # Domains Source: https://docs.orbits.africa/api/domains Add custom domains to a team, attach them to projects, check their DNS, and list a project's branch addresses. A domain belongs to the team and points at one project (and optionally one branch, or a redirect). Add it, then point it at Orbits the way its `dns_mode` says: one record at your DNS provider, or Orbits DNS by changing the domain's nameservers. Orbits checks the records and issues the certificate itself. See [Custom domains](https://docs.orbits.africa/domains/custom-domains). Endpoints: - `GET /v1/teams/{team}/projects/{project}/branch-addresses`: A project's branch addresses - `GET /v1/teams/{team}/domains`: The team's domains - `POST /v1/teams/{team}/domains`: Add a domain - `GET /v1/teams/{team}/domains/preview`: What adding a domain would do - `GET /v1/teams/{team}/domains/{domain}`: A domain - `PATCH /v1/teams/{team}/domains/{domain}`: Change what a domain serves - `DELETE /v1/teams/{team}/domains/{domain}`: Remove a domain - `POST /v1/teams/{team}/domains/{domain}/checks`: Look for the domain's DNS now ## The domain object - `id` (string, required) - `name` (string, required) - `apex` (string, required): The registrable part. - `host` (string, required): What precedes the apex; `@` for the apex itself. - `dns` (string, required): `external`: the team keeps its DNS provider and adds one record. `orbits`: the team hands the domain's DNS to Orbits (an apex's nameservers at its registrar, or NS records for a subdomain at its parent's DNS). One of `external`, `orbits`. - `state` (string, required): `pending`: its record isn't there yet. `valid`: DNS points at Orbits. `misconfigured`: a record is there but points elsewhere (`seen` says where). One of `pending`, `valid`, `misconfigured`. - `project` (null or object, required): What it serves or redirects for; null is "Not in use". - `id` (string, required) - `slug` (string, required) - `name` (string, required) - `branch` (string or null, required): The branch whose newest ready preview it serves; null for production. - `redirect` (null or Redirect, required) - `to` (string, required): The hostname it sends visitors to, keeping the path. - `status` (integer, required): One of `301`, `308`. - `required_record` (object or null, required): The one record an external domain needs at its DNS provider: an A record at an apex (a CNAME can't sit there), a CNAME below it. Null on Orbits DNS, which keeps the record itself. - `type` (string, required): One of `A`, `CNAME`. - `name` (string, required) - `value` (string, required) - `seen` (string or null, required): What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there. - `nameservers` (object or null, required): An Orbits DNS zone's nameservers: for an apex, to set at its registrar; for a subdomain zone, to add as NS records for it at its parent's DNS. `pointing` once the zone is handed to them. Null for any other domain, including names inside a zone. - `names` (array of string, required) - `pointing` (boolean, required) - `email` (string or null, required): The provider Email setup added records for, on an Orbits DNS zone. One of `zoho`, `google`, `microsoft`. - `certificate` (object, required) - `state` (string, required): `none`: not needed yet (DNS not found, or the domain isn't in use). `pending`: DNS points here and the certificate is being issued; Orbits waits until public DNS answers for the name before asking Let's Encrypt. `failed`: the last try failed; it is tried again 5, 15, 30, then 60 minutes after each failure. One of `none`, `pending`, `active`, `failed`. - `issued_at` (string or null, required) - `expires_at` (string or null, required): It renews on its own about 30 days before. - `checked_at` (string or null, required) - `created_at` (string, required) ## A project's branch addresses ```http GET /v1/teams/{team}/projects/{project}/branch-addresses ``` The branch rows on a project's Domains page ("Follows the branch"): one address per branch with a ready preview, serving that branch's newest ready preview. The address is `-git-.theorbits.app` (`orders-git-feat-apple-pay.theorbits.app`), one label under the free addresses' domain so their certificate covers it; a long branch is shortened and given a short hash. Show `host` as it is rather than building it. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/branch-addresses" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "branch": "feat/apple-pay", "host": "orders-git-feat-apple-pay.theorbits.app", "url": "https://my-app.theorbits.app", "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "deployed_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## The team's domains ```http GET /v1/teams/{team}/domains ``` The team's Domains and DNS page: every domain the team added, newest first, with the page's counts and the projects for its filter. A project's Domains page is this list with `project` set. Teams have a handful of domains, so the list isn't paged. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `q` (string): Part of a domain's name or its project's name. At most 253 characters. - `state` (string): One of `pending`, `valid`, `misconfigured`. - `dns` (string): One of `external`, `orbits`. - `project` (string): A project's `id` or `slug`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/domains" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "as_of": "2026-11-10T09:30:00Z", "items": [ { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ], "summary": { "total": 1, "apex": 1, "orbits": [ "orbits" ], "pending": 1, "misconfigured": 1 }, "projects": [ { "id": "id", "slug": "my-app", "name": "my-app" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Add a domain ```http POST /v1/teams/{team}/domains ``` The Add domain dialog, on the team's Domains and DNS page or a project's Domains page. The domain starts `pending`. With `dns: external`, show `required_record` for the team to add at its DNS provider. With `dns: orbits`, the domain becomes a zone of its own: show `nameservers.names` for the team to set at its registrar (an apex, `host: "@"`) or to add as NS records for that name at its parent's DNS (a subdomain such as `dns-test.example.com`); Orbits then serves the whole zone, keeps the records its projects need, and the team manages the rest (`.../records`). A name inside a zone the team already has on Orbits DNS is on Orbits DNS too, whatever `dns` says: its record is created for it. Zones never nest: a zone around one already on Orbits DNS is refused (422 `dns`), and so is one inside or around another team's (409 `domain`). Orbits looks for it every minute (and at once with `POST .../checks`), issues the certificate once it's found, then serves the project on it. The person who added it gets an email when it's live, and another if DNS still isn't there an hour later. A domain the team already has that serves nothing (a zone moved to Orbits DNS before any project was picked) can be typed into a project's Add domain dialog like a new one: this call links it (200) instead of refusing it. `GET .../domains/preview` says beforehand what adding a name would do, for the dialog's note. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. Body: - `domain` (string, required): As typed: a scheme, path or trailing dot comes off, and it is lowercased. At most 253 characters. - `dns` (string): `external`: the team keeps its DNS provider and adds one record. `orbits`: the team hands the domain's DNS to Orbits (an apex's nameservers at its registrar, or NS records for a subdomain at its parent's DNS). One of `external`, `orbits`. - `project` (string or null): A project's `id` or `slug`. - `branch` (string or null): Serve this branch's newest ready preview instead of production. Needs `project`. At most 128 characters. - `to` (string or null): Redirect every request (308, same path) to this hostname instead of serving. At most 253 characters. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "domain": "shop.shadyventures.ng" }' ``` Response `200`: ```json { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: This team already has the domain and it serves something already, or the request names nothing for it to serve; or another team has it (`errors[0].field` is `domain`). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## What adding a domain would do ```http GET /v1/teams/{team}/domains/preview ``` The Add domain dialogs' note, as the person types: whether the name would use outside DNS (one record to add, `required_record`), sit inside one of the team's Orbits DNS zones (`zone`, Orbits adds the record), or become a zone of its own (`nameservers`); and whether the team has it already (`existing`, which Add links to the project when it serves nothing). Nothing is saved. Checks the same rules as Add, with the same errors. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `domain` (string, required): At most 253 characters. - `dns` (string): One of `external`, `orbits`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/domains/preview?domain=domain" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "domain": "pay.shadyventures.ng", "apex": "apex", "host": "pay", "dns": "external", "zone": "shadyventures.com", "required_record": { "type": "A", "name": "my-app", "value": "value" }, "nameservers": [ "nameservers" ], "existing": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: Another team has the domain, or a zone of another team's holds or sits inside it (`errors[0].field` is `domain`). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## A domain ```http GET /v1/teams/{team}/domains/{domain} ``` A domain's page: its state, the record it needs and what the last check found, the hostname card (which project and branch it serves, or where it redirects) and its certificate. While it's `pending`, refresh the page every few seconds or call `POST .../checks`. **Permissions:** Any team member. A non-member, or a domain of another team, gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Change what a domain serves ```http PATCH /v1/teams/{team}/domains/{domain} ``` The hostname card's Change: point the domain at another project, a branch, production again, a redirect, or nothing (`project: null` leaves it "Not in use"). Send only what changes; `null` clears a field. The name and DNS mode don't change: remove the domain and add it again. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Body: - `project` (string or null) - `branch` (string or null): At most 128 characters. - `to` (string or null): At most 253 characters. Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project": null, "branch": null, "to": null }' ``` Response `200`: ```json { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Remove a domain ```http DELETE /v1/teams/{team}/domains/{domain} ``` Remove domain, after the dialog's confirmation. The project stops answering on it within a minute and its certificate is deleted. The record at the team's DNS provider stays until they delete it there. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/domains/example.com" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Removed. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Look for the domain's DNS now ```http POST /v1/teams/{team}/domains/{domain}/checks ``` Check now. Orbits looks up the domain's DNS at once and answers with the domain as it stands, `checked_at` included. A domain checked in the last 10 seconds isn't looked up again; the answer is the same. Orbits also checks by itself every minute while a domain waits, and every 10 minutes once it's valid. A certificate follows within about a minute of DNS being found. **Permissions:** Any team member: checking changes nothing the team chose. A non-member gets 404. This call ignores `Idempotency-Key`. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains/example.com/checks" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "shop.shadyventures.ng", "apex": "shadyventures.ng", "host": "shop", "dns": "external", "state": "pending", "project": { "id": "dom_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "branch": null, "redirect": { "to": "to", "status": 301 }, "required_record": { "type": "A", "name": "shop", "value": "cname.theorbits.app" }, "seen": "CNAME old-host.example.net", "nameservers": { "names": [ "ns1.theorbits.app", "ns2.theorbits.app" ], "pointing": false }, "email": "zoho", "certificate": { "state": "none", "issued_at": "2026-11-10T09:30:00Z", "expires_at": "2026-11-10T09:30:00Z" }, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `503`: A store this endpoint reads is unreachable. Try again shortly. --- # DNS Source: https://docs.orbits.africa/api/dns Records of a domain on Orbits DNS, zone file imports, and email records. These routes manage the records of a domain whose nameservers are Orbits' (`ns1.theorbits.app` and `ns2.theorbits.app`). See [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) and [Email records](https://docs.orbits.africa/domains/email-records). Endpoints: - `GET /v1/teams/{team}/domains/{domain}/records`: A zone's records - `POST /v1/teams/{team}/domains/{domain}/records`: Add a record - `PUT /v1/teams/{team}/domains/{domain}/records/{record}`: Edit a record - `DELETE /v1/teams/{team}/domains/{domain}/records/{record}`: Delete a record - `POST /v1/teams/{team}/domains/{domain}/zone-imports`: Import a BIND zone file - `GET /v1/teams/{team}/domains/{domain}/email`: The Email setup dialog - `PUT /v1/teams/{team}/domains/{domain}/email`: Set up email for a zone ## The DNS record object - `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`. - `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters. - `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters. - `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`. - `id` (string, required) - `managed` (boolean, required): Orbits keeps it for a project; it can't be changed here. - `used_by` (null or object, required) - `kind` (string, required): One of `project`, `email`. - `project` (object) - `id` (string, required) - `slug` (string, required) - `name` (string, required) - `updated_at` (string, required) ## A zone's records ```http GET /v1/teams/{team}/domains/{domain}/records ``` The DNS records table on an Orbits DNS domain's page: every record the zone serves, the team's own and the ones Orbits manages for its projects (`used_by.kind: project`, `managed: true`, locked: they change from that project's Domains page). Email records (`used_by.kind: email`) came with Email setup and stay editable. The zone also has its SOA and NS records, which aren't listed. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0, "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "managed": false, "used_by": { "kind": "project", "project": { "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" } }, "updated_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Add a record ```http POST /v1/teams/{team}/domains/{domain}/records ``` Add a DNS record. It's served within about a minute. A name Orbits manages for a project (the apex and `www` of a zone in use, a subdomain added as a domain) can't take another record there: add the domain from the project's Domains page instead. A CNAME can't share its name with any other record, and can't sit at `@`. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Body: - `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`. - `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters. - `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters. - `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0 }' ``` Response `201`: ```json { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0, "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "managed": false, "used_by": { "kind": "project", "project": { "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" } }, "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Edit a record ```http PUT /v1/teams/{team}/domains/{domain}/records/{record} ``` The record menu's Edit: the record is replaced by what's sent, under the same rules as adding one. Records Orbits manages for a project can't be edited (409). **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. - `record` Body: - `type` (string, required): One of `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `CAA`. - `name` (string, required): Relative to the zone; `@` for the apex. At most 253 characters. - `value` (string, required): An MX record's is its priority and server; a TXT record's is its text without quotes. At most 2048 characters. - `ttl` (integer, required): Seconds; `0` is Auto (5 minutes). One of `0`, `60`, `300`, `3600`, `86400`. Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records/rec_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0 }' ``` Response `200`: ```json { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0, "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "managed": false, "used_by": { "kind": "project", "project": { "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" } }, "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Delete a record ```http DELETE /v1/teams/{team}/domains/{domain}/records/{record} ``` The record menu's Delete, after its confirmation. Records Orbits manages for a project can't be deleted (409): remove the domain from the project instead. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. - `record` Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/domains/example.com/records/rec_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Deleted. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Import a BIND zone file ```http POST /v1/teams/{team}/domains/{domain}/zone-imports ``` Import zone file. Send the pasted or dropped file with `dry_run: true` to show "4 records found: 1 new, 3 already here", then again without it to add the new ones. Records already in the zone (same type, name and value) are left as they are. Lines Orbits can't use (SOA, NS, records for another domain, types it doesn't host, names Orbits manages for a project) are counted in `skipped`, not guessed at. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Body: - `zone` (string, required): The zone file as text. At most 200000 characters. - `dry_run` (boolean): Defaults to `false`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/domains/example.com/zone-imports" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "zone": "zone" }' ``` Response `200`: ```json { "found": 1, "added": 1, "existing": 1, "skipped": 1, "records": [ { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0 } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## The Email setup dialog ```http GET /v1/teams/{team}/domains/{domain}/email ``` Set up email for a zone: the provider set up now (the Active badge), how many of the zone's records came with it or are mail records ("Already set up · 5 records"), and for each provider the records Setup would add, less any that would clash with the team's own or Orbits' (for "Adds 5 MX records and SPF"). `other` is "Something else" and adds nothing. A name inside a zone answers with its zone's. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/domains/example.com/email" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "zone": "shadyventures.com", "provider": "zoho", "email_records": 1, "providers": [ { "id": "zoho", "records": [ { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0 } ] } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Set up email for a zone ```http PUT /v1/teams/{team}/domains/{domain}/email ``` Email setup: the zone's MX and SPF records for one provider, in place of the last provider's (records added by Email setup, `used_by.kind: email`). DMARC and the team's other TXT records stay. DKIM keys belong to the team's mail account, so they're added as records afterwards. `other` ("Something else") clears the provider and keeps every record, for the team to manage. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `domain`: The domain's name, or its `dom_` id. Body: - `provider` (string, required): One of `zoho`, `google`, `microsoft`, `other`. Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/domains/example.com/email" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "provider": "zoho" }' ``` Response `200`: ```json { "items": [ { "type": "A", "name": "@", "value": "10 mx.zoho.com", "ttl": 0, "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "managed": false, "used_by": { "kind": "project", "project": { "id": "rec_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" } }, "updated_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Runtime logs and observability Source: https://docs.orbits.africa/api/logs What a project's apps print and the requests they serve, and the totals behind the Observability page. Runtime logs are what a project's deployments write while they run, and its requests, kept for 7 days. Build logs are a deployment's: see [Deployments](https://docs.orbits.africa/api/deployments). See [Runtime logs](https://docs.orbits.africa/observe/runtime-logs) and [Observability](https://docs.orbits.africa/observe/observability). Endpoints: - `GET /v1/teams/{team}/projects/{project}/logs`: Runtime logs - `GET /v1/teams/{team}/projects/{project}/logs/{log}`: One runtime log entry - `GET /v1/teams/{team}/projects/{project}/observability`: Production's requests, errors and latency ## The runtime log object - `id` (string, required) - `at` (string, required): With milliseconds. - `source` (string, required): One of `requests`, `functions`. - `level` (string, required): One of `info`, `warning`, `error`. - `status` (integer or null, required): A request's HTTP status. - `method` (string or null, required) - `path` (string or null, required): Without the query string. - `duration_ms` (integer or null, required): From the edge receiving the request to the last byte of the answer. - `message` (string or null, required): An output line, without colour codes; at most 8192 characters. - `stream` (string or null, required): One of `stdout`, `stderr`. - `request_id` (string or null, required): The edge's ID for a request, also sent to the app as `X-Request-Id`. - `host` (string or null, required) - `region` (string, required) - `deployment` (object or null, required) - `id` (string, required) - `sha` (string or null, required) - `headers` (array of array of string, required): Some request headers, as `[name, value]` pairs: user-agent, accept, content-type, referer, and x-forwarded-for masked. Cookies and authorization are never stored. ## Runtime logs ```http GET /v1/teams/{team}/projects/{project}/logs ``` The Logs page: every request the edge sent to one of the project's deployments (`source: requests`), and every line its deployments printed while running (`source: functions`), newest first. Build logs are on each deployment (`GET .../deployments/{deployment}/logs`). Entries are kept for 7 days. A request has `status`, `method`, `path` and `duration_ms`, and no `message`. An output line has `message` and `stream`, and null `status`, `method`, `path` and `duration_ms`. Requests and output lines are not linked: an app's output is whatever it printed, whichever request it was serving. Client IP addresses are stored masked (`102.89.x.x`), and query strings are not stored. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `q` (string): Matches a path or message (any case), or exactly a request ID, status or method. A request ID on its own (32 hex characters, as the edge makes them) matches only that request. At most 200 characters. - `source` (string): One of `requests`, `functions`. - `level` (string): A request is `error` for 5xx and `warning` for 4xx. An output line is `warning` when it mentions a warning, and `error` when it was written to stderr or mentions an error. One of `info`, `warning`, `error`. - `status` (string): Requests only; output lines never match. One of `2xx`, `3xx`, `4xx`, `5xx`. - `range` (string): One of `1h`, `24h`, `7d`. Defaults to `1h`. - `limit` (integer): From 1 to 500. Defaults to `50`. - `cursor` (string): `next_cursor` from the previous page. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/logs" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "as_of": "2026-11-10T09:30:00Z", "items": [ { "id": "log_019a16dc-3a1f-7c2e-9b1d-2f4e8a6b0c11", "at": "2026-11-10T09:30:00Z", "source": "requests", "level": "info", "status": null, "method": "GET", "path": "/checkout", "duration_ms": null, "message": null, "stream": "stdout", "request_id": null, "host": "shop.theorbits.app", "region": "abj-1", "deployment": { "id": "log_01jc8x6e4mq2v7r9y3t5b0zp8w", "sha": null }, "headers": [ [ "headers" ] ] } ], "total": 1, "total_capped": false, "next_cursor": null } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## One runtime log entry ```http GET /v1/teams/{team}/projects/{project}/logs/{log} ``` One entry for the Logs inspector, when the one in the URL is not on the current page. 404 once it is older than 7 days. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `log`: A `log_` id from `GET .../logs`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/logs/log_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "log_019a16dc-3a1f-7c2e-9b1d-2f4e8a6b0c11", "at": "2026-11-10T09:30:00Z", "source": "requests", "level": "info", "status": null, "method": "GET", "path": "/checkout", "duration_ms": null, "message": null, "stream": "stdout", "request_id": null, "host": "shop.theorbits.app", "region": "abj-1", "deployment": { "id": "log_01jc8x6e4mq2v7r9y3t5b0zp8w", "sha": null }, "headers": [ [ "headers" ] ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Production's requests, errors and latency ```http GET /v1/teams/{team}/projects/{project}/observability ``` The Observability page: production's traffic over a range, from the runtime logs (the edge's requests to the project's production builds, at its address or a build's own). Requests and server errors (5xx) per bucket with p75 and p99 response times, totals with p50, p75 and p99 against the period before, the busiest routes, requests by status class and by region, and the routes for the Route filter. Times are milliseconds from the edge receiving a request to its last byte. Routes group a path's ids (`/products/8412` is `/products/[id]`) and a static folder's files (`/_next/*`). Percentiles are exact. Buckets are 12 x 5 minutes (`1h`), 24 x an hour (`24h`) or 7 x a day (`7d`), on Lagos's clock; the last is the one still filling. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `range` (string): Buckets: 12 x 5 minutes, 12 x 30 minutes (the project overview's health), 24 x an hour, 7 x a day. One of `1h`, `6h`, `24h`, `7d`. Defaults to `24h`. - `route` (string): A route from `all_routes`. At most 500 characters. - `status` (string): Narrows everything but `statuses`. One of `2xx`, `3xx`, `4xx`, `5xx`. - `region` (string): A region code; `abj-1` is the only one with traffic. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/observability" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "as_of": "2026-11-10T09:30:00Z", "range": "1h", "bucket_seconds": 3600, "totals": { "requests": 1, "errors": 1, "p50_ms": 1, "p75_ms": 1, "p99_ms": 1 }, "previous": { "requests": 1, "errors": 1, "p50_ms": 1, "p75_ms": 1, "p99_ms": 1 }, "buckets": [ { "start": "2026-11-10T09:30:00Z", "requests": 1, "errors": 1, "p75_ms": 1, "p99_ms": 1 } ], "routes": [ { "route": "/products/[id]", "requests": 1, "errors": 1, "p75_ms": 1, "p99_ms": 1 } ], "statuses": { "2xx": 1, "3xx": 1, "4xx": 1, "5xx": 1 }, "regions": [ { "region": "abj-1", "requests": 1 } ], "all_routes": [ "all-routes" ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. --- # Analytics and Speed Insights Source: https://docs.orbits.africa/api/insights Read a project's visitors and Web Vitals, and turn collection on or off. Analytics and Speed Insights come from the beacons sent by `@useorbits/analytics` and `@useorbits/speed-insights` in your app. Both are part of the Pro plan: on Free, reads answer `enabled: false` with `locked: true`, and turning one on is `402`. See [Analytics](https://docs.orbits.africa/observe/analytics) and [Speed Insights](https://docs.orbits.africa/observe/speed-insights). Endpoints: - `GET /v1/teams/{team}/projects/{project}/analytics`: A project's visitors and page views - `PUT /v1/teams/{team}/projects/{project}/analytics`: Turn Analytics on or off - `GET /v1/teams/{team}/projects/{project}/analytics/event`: One custom event and its properties - `GET /v1/teams/{team}/projects/{project}/speed-insights`: A project's Web Vitals from real visits - `PUT /v1/teams/{team}/projects/{project}/speed-insights`: Turn Speed Insights on or off ## A project's visitors and page views ```http GET /v1/teams/{team}/projects/{project}/analytics ``` The Analytics page: page views the project's visitors' browsers sent with `@useorbits/analytics` (the edge's `/_orbits/analytics.js`, which sends beacons to `/_orbits/e` on the project's own host), to its production deployments only (not a preview's), over a range against the span before it. `buckets` are the range's hours (`24h`) or Lagos days (`7d`, `30d`), the last one still filling; `previous_buckets` are the span before, in the same order. A visitor is counted once a Lagos day: nothing identifies them across days, and neither their address nor their browser is kept. A bounce is a visitor with one page view. `pages` are by the route the framework named (`/blog/[slug]`, from the Next.js, SvelteKit and Astro components), or else the path with its ids grouped (`/products/8412` is `/products/[id]`). `referrers` are other sites' hosts; `host: null` is a visit nobody linked to. `countries` is empty until the edge looks them up. `events` are custom events (`track()`), most sent first. Lists keep their top ten. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "enabled": false, "locked": true } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Turn Analytics on or off ```http PUT /v1/teams/{team}/projects/{project}/analytics ``` The Analytics page's Enable switch. While it's off, production's hosts don't serve `/_orbits/analytics.js` and page views and events aren't logged; the edge picks a change up within seconds. Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `analytics`). Turning it off is always allowed. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `enabled` (boolean, required) Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "enabled": false }' ``` Response `200`: ```json { "enabled": false } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## One custom event and its properties ```http GET /v1/teams/{team}/projects/{project}/analytics/event ``` A custom event from the Analytics page's `events` (sent with `track(name, properties)`) over a range, production only: how often it was sent, by how many visitors, and its properties, ten at most, each with its ten commonest values. A value that isn't a string is shown as its JSON (`3`, `true`, `null`). **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `name` (string, required): At most 255 characters. - `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics/event?name=my-app" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "enabled": false } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## A project's Web Vitals from real visits ```http GET /v1/teams/{team}/projects/{project}/speed-insights ``` The Speed Insights page: Web Vitals the project's visitors' browsers measured and sent with `@useorbits/speed-insights` (the edge's `/_orbits/speed-insights.js`) from its production deployments, on one kind of device (`mobile` counts tablets), at the 75th percentile. LCP, INP, FCP and TTFB are milliseconds, CLS a unitless score. `score` is 0 to 100 from the p75s there are, as Lighthouse scores each metric (90 at its good line, 50 at its median) weighted FCP 15%, LCP 30%, INP 30% and CLS 25%; TTFB is shown but not scored; null without any. `lcp` is LCP's p75 by bucket (null where none was measured). `routes` are the most visited, ten at most, by the route the framework named or the path with its ids grouped, with each vital's p75 or null. `targets` are the elements (CSS selectors) most often behind LCP, INP and CLS, five each, with how often and their p75. `connections` are LCP samples by the connection they were measured on. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`. - `device` (string): One of `mobile`, `desktop`. Defaults to `mobile`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/speed-insights" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "enabled": false, "locked": true } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Turn Speed Insights on or off ```http PUT /v1/teams/{team}/projects/{project}/speed-insights ``` The Speed Insights page's Enable switch. While it's off, production's hosts don't serve `/_orbits/speed-insights.js` and vitals aren't logged; the edge picks a change up within seconds. Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `speed_insights`). Turning it off is always allowed. **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `enabled` (boolean, required) Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/speed-insights" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "enabled": false }' ``` Response `200`: ```json { "enabled": false } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. --- # Alerts Source: https://docs.orbits.africa/api/alerts Alert rules on a project's metrics, their history, and the team's alert channels. An alert watches one of a project's metrics over a window and notifies the team's channels when it crosses its threshold, and again when it recovers. Preview a rule against recent data before saving it. See [Alerts](https://docs.orbits.africa/observe/alerts). Endpoints: - `GET /v1/teams/{team}/projects/{project}/alerts`: A project's alert rules and their state - `POST /v1/teams/{team}/projects/{project}/alerts`: Create an alert rule - `POST /v1/teams/{team}/projects/{project}/alerts/preview`: How much traffic a draft rule would see - `PATCH /v1/teams/{team}/projects/{project}/alerts/{alert}`: Change or switch an alert rule - `DELETE /v1/teams/{team}/projects/{project}/alerts/{alert}`: Delete an alert rule - `GET /v1/teams/{team}/projects/{project}/alerts/{alert}/events`: When a rule fired and resolved - `GET /v1/teams/{team}/alert-channels`: The team's alert webhook - `PUT /v1/teams/{team}/alert-channels/webhook`: Set the team's alert webhook - `DELETE /v1/teams/{team}/alert-channels/webhook`: Remove the team's alert webhook - `POST /v1/teams/{team}/alert-channels/webhook/test`: Send a test event to the webhook ## The alert object - `id` (string, required) - `name` (string, required): At most 60 characters. - `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`. - `direction` (string, required): `below` only for `requests`. One of `above`, `below`. - `threshold` (number, required) - `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`. - `routes` (array of string, required): Routes as Observability names them; a trailing `*` matches a prefix. Empty for all routes. - `channels` (array of string, required) - `on` (boolean, required) - `state` (string, required): One of `ok`, `firing`. - `since` (string, required): When it last fired or resolved, or was created or changed. - `last_value` (number or null, required): The value at the last check; null before one, or with too little traffic. - `checked_at` (string or null, required) - `created_at` (string, required) - `updated_at` (string, required) ## A project's alert rules and their state ```http GET /v1/teams/{team}/projects/{project}/alerts ``` The Alerts card on Observability: every rule of the project, oldest first, with its state. A rule watches production's requests (the same traffic as Observability) and is checked every minute, at :30, over its last `window_minutes` whole minutes. It fires as soon as its value is past the line (above `threshold`, or below it for `direction: below`), and resolves after 3 checks in a row back on the right side. `error-rate`, `p75` and `p99` need 20 requests in the window to say anything: under that a rule can't fire, and `last_value` is null. A firing rule counts such a check toward resolving, unless what few requests there were are still past the line, and resolves with `reason: quiet` when the last of the 3 is one. `webhook_configured` says whether `webhook` can be offered as a channel. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11", "name": "my-app", "metric": "error-rate", "direction": "above", "threshold": 1, "window_minutes": 1, "routes": [ "routes" ], "channels": [ "webhook" ], "on": false, "state": "ok", "since": "2026-11-10T09:30:00Z", "last_value": null, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ], "webhook_configured": false } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Create an alert rule ```http POST /v1/teams/{team}/projects/{project}/alerts ``` The Create alert form. The rule starts `ok` and is first checked at the next :30. 422 names the field: a name already used in the project, `direction: below` for anything but `requests`, an `error-rate` threshold of 100 or more, a route that doesn't start with `/` or has a `*` anywhere but the end, or `webhook` in `channels` while the team has no webhook (`webhook_configured` on the list). **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `name` (string, required): At most 60 characters. - `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`. - `direction` (string): One of `above`, `below`. Defaults to `above`. - `threshold` (number, required): At most 1000000. - `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`. - `routes` (array of string): At most 10 items. - `channels` (array of string, required) - `on` (boolean): Defaults to `true`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app", "metric": "error-rate", "threshold": 1, "window_minutes": 1, "channels": [ "webhook" ] }' ``` Response `201`: ```json { "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11", "name": "my-app", "metric": "error-rate", "direction": "above", "threshold": 1, "window_minutes": 1, "routes": [ "routes" ], "channels": [ "webhook" ], "on": false, "state": "ok", "since": "2026-11-10T09:30:00Z", "last_value": null, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## How much traffic a draft rule would see ```http POST /v1/teams/{team}/projects/{project}/alerts/preview ``` For the Create and Edit forms. `median_requests` is the median number of requests a window of this size held over the last 24 hours on these routes (minutes without traffic count as none). When it is under `minimum_requests` (20 for `error-rate`, `p75` and `p99`; 0 for `requests`), warn under the window field, for example "These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes." It is a warning: the form can still be saved. `value` is what the rule would measure now, or null with too little traffic. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`. - `direction` (string): One of `above`, `below`. - `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`. - `routes` (array of string): At most 10 items. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/preview" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "metric": "error-rate", "window_minutes": 1 }' ``` Response `200`: ```json { "median_requests": 1, "minimum_requests": 1, "value": null } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. - `503`: A store this endpoint reads is unreachable. Try again shortly. ## Change or switch an alert rule ```http PATCH /v1/teams/{team}/projects/{project}/alerts/{alert} ``` The rule's switch, and the Edit dialog. Send only what changes. Any change, switching it off or on included, starts the rule again from `ok`. A rule that was firing first resolves, so a receiver sees its incident close: `reason: changed` for an edit, `off` when switched off. Changing `metric` away from `requests` sets `direction` to `above` unless one is sent. 422 as for create. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `alert`: An `alr_` id from `GET .../alerts`. Body: - `name` (string): At most 60 characters. - `metric` (string): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`. - `direction` (string): One of `above`, `below`. - `threshold` (number): At most 1000000. - `window_minutes` (integer): One of `1`, `5`, `10`, `30`. - `routes` (array of string): At most 10 items. - `channels` (array of string) - `on` (boolean) Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my-app", "metric": "error-rate", "direction": "above", "threshold": 1, "window_minutes": 1, "routes": [ "routes" ], "channels": [ "webhook" ], "on": false }' ``` Response `200`: ```json { "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11", "name": "my-app", "metric": "error-rate", "direction": "above", "threshold": 1, "window_minutes": 1, "routes": [ "routes" ], "channels": [ "webhook" ], "on": false, "state": "ok", "since": "2026-11-10T09:30:00Z", "last_value": null, "checked_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Delete an alert rule ```http DELETE /v1/teams/{team}/projects/{project}/alerts/{alert} ``` Deletes the rule and its history. A rule that was firing sends `alert.resolved` with `reason: deleted` first. **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `alert`: An `alr_` id from `GET .../alerts`. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Deleted. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## When a rule fired and resolved ```http GET /v1/teams/{team}/projects/{project}/alerts/{alert}/events ``` A rule's history, newest first, kept 90 days, with how each notification went (`deliveries`: one per channel, `pending` while it is still being tried, up to 5 times over about 30 minutes). **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `alert` Query parameters: - `limit` (integer): From 1 to 100. Defaults to `20`. - `cursor` (string) Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w/events" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "id", "kind": "fired", "reason": "recovered", "value": null, "at": "2026-11-10T09:30:00Z", "deliveries": [ { "channel": "webhook", "status": "pending", "error": null, "at": "2026-11-10T09:30:00Z" } ] } ], "next_cursor": null } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## The team's alert webhook ```http GET /v1/teams/{team}/alert-channels ``` The webhook every rule with the `webhook` channel sends to, one per team, or null. The secret is never shown again after it is made; `secret_last4` identifies it. **Permissions:** Owner or admin of the team. Members and viewers get 403 (the list's `webhook_configured` tells them whether one is set). A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/alert-channels" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "webhook": { "url": "https://my-app.theorbits.app", "secret_last4": "secret-last4", "updated_at": "2026-11-10T09:30:00Z" } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Set the team's alert webhook ```http PUT /v1/teams/{team}/alert-channels/webhook ``` Sets the URL (https only). The first time, or with `rotate_secret`, a new secret is made and returned in `secret`, this once; the old one stops working at once. Otherwise `secret` is null and the secret is kept. Every request Orbits sends is a JSON `POST` with `X-Signature-256: sha256=` (HMAC-SHA256 of the raw body with the secret), `X-Delivery-Id` (the same on every retry of one notification) and `X-Orbits-Event` (`alert.fired`, `alert.resolved` or `alert.test`). The body is an AlertWebhookPayload. A 2xx answer is delivered; anything else, or no answer in 10 seconds, is tried again. Redirects aren't followed, and addresses that aren't on the public internet are refused. The webhook-receiver template verifies these as they are. **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. Body: - `url` (string, required): An https URL without a user name or password. At most 2000 characters. - `rotate_secret` (boolean): Defaults to `false`. Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://my-app.theorbits.app" }' ``` Response `200`: ```json { "webhook": { "url": "https://my-app.theorbits.app", "secret_last4": "secret-last4", "updated_at": "2026-11-10T09:30:00Z" }, "secret": null } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Remove the team's alert webhook ```http DELETE /v1/teams/{team}/alert-channels/webhook ``` Notifications still waiting for the webhook fail with "The team has no webhook". **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Removed. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Send a test event to the webhook ```http POST /v1/teams/{team}/alert-channels/webhook/test ``` Sends a signed `alert.test` now and says how it went: `delivered` for a 2xx answer, otherwise the receiver's `status` (null when nothing answered) and an `error` to show. 404 when the team has no webhook. **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook/test" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "delivered": false, "status": null, "error": null } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Feature flags Source: https://docs.orbits.africa/api/flags Create and change a project's feature flags, their environments and targeting rules. A flag has a value per environment and, in each, rules that pick a value for some visitors. Your app reads flags with `@useorbits/flags`, using the environment's key that deployments get as `ORBITS_FLAGS`. See [Feature flags](https://docs.orbits.africa/features/flags). Endpoints: - `GET /v1/teams/{team}/projects/{project}/flags`: A project's feature flags - `POST /v1/teams/{team}/projects/{project}/flags`: Create a flag - `GET /v1/teams/{team}/projects/{project}/flag-keys`: Each environment's ORBITS_FLAGS key - `GET /v1/teams/{team}/projects/{project}/flags/{flag}`: A flag, its history and who it was checked for - `PATCH /v1/teams/{team}/projects/{project}/flags/{flag}`: Change a flag's description - `DELETE /v1/teams/{team}/projects/{project}/flags/{flag}`: Delete a flag - `PUT /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}`: Switch a flag, set its rollout or its value in one environment - `POST /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules`: Add a targeting rule - `PATCH /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}`: Change what a rule serves - `DELETE /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}`: Remove a rule ## The flag object - `key` (string, required) - `description` (string, required) - `type` (string, required): One of `boolean`, `string`, `number`. - `environments` (object, required) - `production` (FlagEnvironment, required) - `on` (boolean, required): A boolean flag's switch; always true for the others. - `rollout` (integer, required): From 1 to 100. - `value` (string | number or null, required): A string or number flag's value; null for a boolean. - `rules` (array of FlagRule, required) - `id` (string, required) - `attribute` (string, required) - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`. - `values` (array of string, required) - `serve` (boolean | string | number, required) - `label` (string, required) - `preview` (FlagEnvironment, required) - `on` (boolean, required): A boolean flag's switch; always true for the others. - `rollout` (integer, required): From 1 to 100. - `value` (string | number or null, required): A string or number flag's value; null for a boolean. - `rules` (array of FlagRule, required) - `id` (string, required) - `attribute` (string, required) - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`. - `values` (array of string, required) - `serve` (boolean | string | number, required) - `label` (string, required) - `development` (FlagEnvironment, required) - `on` (boolean, required): A boolean flag's switch; always true for the others. - `rollout` (integer, required): From 1 to 100. - `value` (string | number or null, required): A string or number flag's value; null for a boolean. - `rules` (array of FlagRule, required) - `id` (string, required) - `attribute` (string, required) - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`. - `values` (array of string, required) - `serve` (boolean | string | number, required) - `label` (string, required) - `created_by` (FlagPerson, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `avatar_url` (string or null, required) - `updated_by` (FlagPerson, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `avatar_url` (string or null, required) - `created_at` (string, required) - `updated_at` (string, required) ## A project's feature flags ```http GET /v1/teams/{team}/projects/{project}/flags ``` The Flags page: every flag, newest first, with each environment's setting. `q` matches the key or description, `type` narrows to one type; `total` counts them all, for "3 of 5 flags". **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Query parameters: - `q` (string): At most 100 characters. - `type` (string): One of `boolean`, `string`, `number`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": null, "attribute": null, "operator": null, "values": null, "serve": null, "label": null } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": null, "attribute": null, "operator": null, "values": null, "serve": null, "label": null } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": null, "attribute": null, "operator": null, "values": null, "serve": null, "label": null } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ], "total": 1 } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Create a flag ```http POST /v1/teams/{team}/projects/{project}/flags ``` A boolean flag starts off in each environment unless `environments..on` says otherwise, at 100% rollout and with no rules. A string or number flag needs `environments..value` for all three. Keys are lowercase letters, digits and single dashes, unique in the project. **Permissions:** Owners, admins and members. Viewers get 403. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `key` (string, required): At most 48 characters. - `description` (string): At most 120 characters. - `type` (string, required): One of `boolean`, `string`, `number`. - `environments` (object) - `production` (object) - `on` (boolean): A boolean flag's switch. - `value` (string | number): A string or number flag's value. - `preview` (object) - `on` (boolean): A boolean flag's switch. - `value` (string | number): A string or number flag's value. - `development` (object) - `on` (boolean): A boolean flag's switch. - `value` (string | number): A string or number flag's value. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "key": "new-checkout", "type": "boolean" }' ``` Response `201`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Each environment's ORBITS_FLAGS key ```http GET /v1/teams/{team}/projects/{project}/flag-keys ``` Deployments get their environment's key as `ORBITS_FLAGS` (and the API's address as `ORBITS_API_URL`) without asking. These are for code that runs elsewhere: put `development`'s in `.env.local` to read Development's flags locally. A key reads its environment's flags and reports checks, nothing else. **Permissions:** Owners, admins and members. Viewers get 403. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flag-keys" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "production": "ofl_cHJqXzE6cHJvZHVjdGlvbg.k3W…", "preview": "preview", "development": "development" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## A flag, its history and who it was checked for ```http GET /v1/teams/{team}/projects/{project}/flags/{flag} ``` The flag's page. `history` is newest first, 50 at most, each line written as the page says it. `seen` is each environment's last 24 hours as the SDK reported them: `people` the ids it was checked for, `checks` every check, with or without one. **Permissions:** Any team member. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": null, "values": [ null ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": null, "values": [ null ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": null, "values": [ null ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z", "history": [ { "id": "id", "by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "text": "Set Preview rollout to 10%", "at": "2026-11-10T09:30:00Z" } ], "seen": { "production": { "people": 1, "checks": 1 }, "preview": { "people": 1, "checks": 1 }, "development": { "people": 1, "checks": 1 } } } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Change a flag's description ```http PATCH /v1/teams/{team}/projects/{project}/flags/{flag} ``` The key and type never change; make another flag for that. **Permissions:** Owners, admins and members. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` Body: - `description` (string): At most 120 characters. Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "description" }' ``` Response `200`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Delete a flag ```http DELETE /v1/teams/{team}/projects/{project}/flags/{flag} ``` The SDK stops getting it on its next refresh, and code checking it gets the default it passed. **Permissions:** Owners, admins and members. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Deleted. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Switch a flag, set its rollout or its value in one environment ```http PUT /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment} ``` A boolean flag takes `on` and `rollout` (1–100, the share of ids it's on for); a string or number flag takes `value`. Fields left out stay as they are. Deployments see the change within seconds, without a redeploy. **Permissions:** Owners, admins and members. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` - `environment` Body: - `on` (boolean) - `rollout` (integer): From 1 to 100. - `value` (string | number) Example: ```sh curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "on": false, "rollout": 1, "value": "value" }' ``` Response `200`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Add a targeting rule ```http POST /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules ``` Rules are checked in order before the environment's switch: the first that matches decides, `serve` being on or off for a boolean flag and the value for the others. `attribute` names what the app passes to `flag()` (`email`, `id`, `plan`, `user.country`); `one_of` takes several values, every other operator one; comparisons ignore case, and an attribute the app didn't pass matches nothing. 20 rules at most. **Permissions:** Owners, admins and members. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` - `environment` Body: - `attribute` (string, required): At most 64 characters. - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`. - `values` (array of string, required): At most 50 items. - `serve` (boolean | string | number, required) Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "attribute": "email", "operator": "equals", "values": [ "@kudi.ng" ], "serve": false }' ``` Response `201`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Change what a rule serves ```http PATCH /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule} ``` **Permissions:** Owners, admins and members. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` - `environment` - `rule` Body: - `serve` (boolean | string | number, required) Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "serve": false }' ``` Response `200`: ```json { "key": "new-checkout", "description": "description", "type": "boolean", "environments": { "production": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "preview": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] }, "development": { "on": false, "rollout": 1, "value": null, "rules": [ { "id": "id", "attribute": "email", "operator": "equals", "values": [ "values" ], "serve": false, "label": "Email ends with @kudi.ng" } ] } }, "created_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "updated_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Remove a rule ```http DELETE /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule} ``` **Permissions:** Owners, admins and members. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `flag` - `environment` - `rule` Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Removed. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Workflows Source: https://docs.orbits.africa/api/workflows The workflows a project's app defines, and their runs: start, read, cancel and retry. Workflows are defined in your app's code with `@useorbits/workflows`; these routes list them and their runs, start a run, and cancel or retry one. See [Workflows](https://docs.orbits.africa/features/workflows). Endpoints: - `GET /v1/teams/{team}/projects/{project}/workflows`: A project's workflows and recent runs - `POST /v1/teams/{team}/projects/{project}/workflows/{workflow}/runs`: Run a workflow now - `GET /v1/teams/{team}/projects/{project}/workflows/runs/{run}`: One run and its steps - `POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/cancel`: Cancel a running run - `POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/retry`: Retry a failed run from the step that failed ## The workflow run object - `id` (string, required) - `workflow` (string, required) - `state` (string, required): One of `running`, `succeeded`, `failed`, `canceled`. - `trigger` (string, required): One of `schedule`, `event`, `manual`. - `trigger_text` (string, required) - `started_by` (FlagPerson or null, required): Who pressed Run now; null for a schedule or an event. - `id` (string, required) - `name` (string, required) - `email` (string, required) - `avatar_url` (string or null, required) - `started_at` (string, required) - `finished_at` (string or null, required) - `seconds` (integer, required): From start to finish, or so far. - `deployment` (object, required) - `id` (string, required) - `sha` (string or null, required) - `input` (object, required): The JSON it started with. - `output` (object, required): What the workflow returned. - `error` (array of string, required) - `attempts` (string, required) - `next_at` (string or null, required): When the app is called for it next. - `steps` (array of WorkflowStep, required) - `name` (string, required) - `kind` (string, required): One of `step`, `sleep`, `wait`. - `state` (string, required): One of `running`, `succeeded`, `failed`, `waiting`, `skipped`, `canceled`. - `seconds` (integer or null, required): Time spent running over every attempt; null for one not reached. - `detail` (string, required) - `error` (array of string, required): The last attempt's error: message, then where. - `attempts` (integer, required) - `retried_by` (FlagPerson or null, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `avatar_url` (string or null, required) - `wake_at` (string or null, required): A sleep's end, or a wait's timeout. - `event` (string or null, required): What a wait waits for. - `output` (object, required): The step's result; a wait's is the event's data. ## A project's workflows and recent runs ```http GET /v1/teams/{team}/projects/{project}/workflows ``` The Workflows page. `workflows` are what the production deployment's `@useorbits/workflows` lists, read once it went live: each with its trigger as the page says it ("Every 15 minutes", "When order.paid happens"), its last run, and the share of its finished runs in the last 7 days that succeeded (null without any). `runs` are the 50 newest, each with its steps. A run's steps are the `step()`, `sleep()` and `waitFor()` calls it reached, in order. A step `running` with an `error` failed an attempt and is waiting for its retry (`next_at`). Steps the workflow took on its last successful run that this run hasn't reached are listed after them: `waiting` while it runs, `skipped` once it failed or was canceled. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "workflows": [ { "name": "my-app", "description": "description", "schedule": null, "event": null, "retries": 1, "trigger_text": "trigger-text", "last_run": { "id": "id", "state": "running", "at": "2026-11-10T09:30:00Z" }, "success_rate": null } ], "runs": [ { "id": "id", "workflow": "sync-stock", "state": "running", "trigger": "schedule", "trigger_text": "Every 15 minutes", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": 1, "deployment": { "id": "id", "sha": null }, "input": null, "output": null, "error": [ "error" ], "attempts": "3 on step 3", "next_at": "2026-11-10T09:30:00Z", "steps": [ { "name": "update-inventory", "kind": "step", "state": "running", "seconds": null, "detail": "Gave up after 3 attempts", "error": [ "error" ], "attempts": 1, "retried_by": { "id": null, "name": null, "email": null, "avatar_url": null }, "wake_at": "2026-11-10T09:30:00Z", "event": null, "output": null } ] } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Run a workflow now ```http POST /v1/teams/{team}/projects/{project}/workflows/{workflow}/runs ``` Starts a run on the production deployment with `input` (any JSON, 256 KB at most), as Run now does. The builder picks it up within seconds. **Permissions:** Owners, admins and members. Viewers get 403. 404 when the production deployment doesn't list the workflow; 409 without a production deployment. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `workflow` Body: - `input` (object): Any JSON. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/send-welcome-email/runs" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "input": null }' ``` Response `201`: ```json { "id": "id", "workflow": "sync-stock", "state": "running", "trigger": "schedule", "trigger_text": "Every 15 minutes", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": 1, "deployment": { "id": "id", "sha": null }, "input": null, "output": null, "error": [ "error" ], "attempts": "3 on step 3", "next_at": "2026-11-10T09:30:00Z", "steps": [ { "name": "update-inventory", "kind": "step", "state": "running", "seconds": null, "detail": "Gave up after 3 attempts", "error": [ "error" ], "attempts": 1, "retried_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "wake_at": "2026-11-10T09:30:00Z", "event": null, "output": null } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## One run and its steps ```http GET /v1/teams/{team}/projects/{project}/workflows/runs/{run} ``` **Permissions:** Any team member. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `run` Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "id", "workflow": "sync-stock", "state": "running", "trigger": "schedule", "trigger_text": "Every 15 minutes", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": 1, "deployment": { "id": "id", "sha": null }, "input": null, "output": null, "error": [ "error" ], "attempts": "3 on step 3", "next_at": "2026-11-10T09:30:00Z", "steps": [ { "name": "update-inventory", "kind": "step", "state": "running", "seconds": null, "detail": "Gave up after 3 attempts", "error": [ "error" ], "attempts": 1, "retried_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "wake_at": "2026-11-10T09:30:00Z", "event": null, "output": null } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Cancel a running run ```http POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/cancel ``` The app isn't called for it again; a step already running finishes, and its result is dropped. 409 for a run that isn't running. **Permissions:** Owners, admins and members. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `run` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/cancel" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "id": "id", "workflow": "sync-stock", "state": "running", "trigger": "schedule", "trigger_text": "Every 15 minutes", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": 1, "deployment": { "id": "id", "sha": null }, "input": null, "output": null, "error": [ "error" ], "attempts": "3 on step 3", "next_at": "2026-11-10T09:30:00Z", "steps": [ { "name": "update-inventory", "kind": "step", "state": "running", "seconds": null, "detail": "Gave up after 3 attempts", "error": [ "error" ], "attempts": 1, "retried_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "wake_at": "2026-11-10T09:30:00Z", "event": null, "output": null } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## Retry a failed run from the step that failed ```http POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/retry ``` The steps before the failed one keep their results; the failed one runs again with a fresh set of attempts, and the run goes on from there. 409 for a run that didn't fail. **Permissions:** Owners, admins and members. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `run` Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/retry" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "id": "id", "workflow": "sync-stock", "state": "running", "trigger": "schedule", "trigger_text": "Every 15 minutes", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "started_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "seconds": 1, "deployment": { "id": "id", "sha": null }, "input": null, "output": null, "error": [ "error" ], "attempts": "3 on step 3", "next_at": "2026-11-10T09:30:00Z", "steps": [ { "name": "update-inventory", "kind": "step", "state": "running", "seconds": null, "detail": "Gave up after 3 attempts", "error": [ "error" ], "attempts": 1, "retried_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "wake_at": "2026-11-10T09:30:00Z", "event": null, "output": null } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. --- # Sandboxes Source: https://docs.orbits.africa/api/sandboxes Short-lived development machines for a project, with a terminal and a team-only preview address. Pro plan. Sandboxes need the Pro plan: on Free, creating or starting one answers 402. The guide is [Sandboxes](https://docs.orbits.africa/features/sandboxes). The terminal itself is a WebSocket, opened with a 60-second ticket from the terminal-ticket call, so it is not listed here as a JSON endpoint. Endpoints: - `GET /v1/teams/{team}/projects/{project}/sandboxes`: A project's sandboxes - `POST /v1/teams/{team}/projects/{project}/sandboxes`: Start a sandbox - `GET /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}`: A sandbox, its usage and open ports - `DELETE /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}`: Delete a sandbox - `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/stop`: Suspend a sandbox - `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/start`: Resume a sandbox - `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket`: A ticket to open the sandbox's terminal ## The sandbox object - `name` (string, required) - `runtime` (string, required): One of `node22`, `python312`, `go123`. - `size` (string, required): small = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node. One of `small`, `large`. - `source` (string or null, required): What was cloned (e.g. "storefront · main"); null for an empty machine. - `state` (string, required): `stopped` is suspended: the disk is kept and `start` resumes it. One of `starting`, `running`, `stopped`. - `started_at` (string, required) - `stopped_at` (string or null, required) - `started_by` (FlagPerson, required) - `id` (string, required) - `name` (string, required) - `email` (string, required) - `avatar_url` (string or null, required) - `stop_after` (integer, required): Idle minutes before it suspends itself. One of `10`, `30`, `60`, `120`. - `url` (string, required): The sandbox's preview URL (port 3000), reachable by team members only. - `terminal` (array of SandboxTerminalLine, required): The boot and run output so far; live output streams over the terminal WebSocket. - `kind` (string, required): One of `cmd`, `out`, `ok`, `err`. - `text` (string, required) - `usage` (SandboxUsage, required) - `cpu` (integer, required): Percent of the size's vCPU in use. - `memory_gb` (number, required) - `disk_gb` (number, required) - `idle_minutes` (integer, required): Minutes since the last activity; drives the idle suspend. ## A project's sandboxes ```http GET /v1/teams/{team}/projects/{project}/sandboxes ``` The Sandboxes page: every sandbox, the live ones first and then by most recently started. `running` counts the live ones (starting or running) and `limit` is the most a team may run at once, for "2 of 3 running" and to disable Create at the cap. `as_of` is the server's clock, for the page's relative times. The page polls this while any sandbox is `starting`. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "name": "seed-test-data", "runtime": "node22", "size": "small", "source": null, "state": "starting", "started_at": "2026-11-10T09:30:00Z", "stopped_at": "2026-11-10T09:30:00Z", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "stop_after": 10, "url": "https://my-app.theorbits.app", "terminal": [ { "kind": "cmd", "text": "text" } ], "usage": { "cpu": 1, "memory_gb": 1, "disk_gb": 1, "idle_minutes": 1 } } ], "running": 1, "limit": 1, "as_of": "2026-11-10T09:30:00Z" } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Start a sandbox ```http POST /v1/teams/{team}/projects/{project}/sandboxes ``` Provisions a machine and boots it: `state` is `starting`, then `running` once it is up (poll `GET .../sandboxes`). `clone` checks out the project's repository at `main`; `env` copies the Preview environment variables in. `size` caps CPU, memory and disk; `stop_after` is the idle minutes before it suspends itself. Names are lowercase letters, digits and single dashes, unique among the project's live sandboxes. A team runs at most `SandboxPage.limit` sandboxes at once; past that this returns 409 and the page offers to stop one first. **Runtime (v1):** a sandbox is a Docker container on the build host, capped by cgroups, with the terminal backed by `docker exec`. Stronger isolation (Firecracker microVMs) is a later swap that does not change this contract. **Permissions:** Owners, admins and members. Viewers get 403. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. Body: - `name` (string, required): At most 40 characters. - `runtime` (string, required): One of `node22`, `python312`, `go123`. - `size` (string, required): small = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node. One of `small`, `large`. - `clone` (boolean): Check out the project's repository at main. Defaults to `false`. - `env` (boolean): Copy the Preview environment variables in. Defaults to `false`. - `stop_after` (integer): Idle minutes before it suspends itself. One of `10`, `30`, `60`, `120`. Defaults to `30`. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "seed-test-data", "runtime": "node22", "size": "small" }' ``` Response `201`: ```json { "name": "seed-test-data", "runtime": "node22", "size": "small", "source": null, "state": "starting", "started_at": "2026-11-10T09:30:00Z", "stopped_at": "2026-11-10T09:30:00Z", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "stop_after": 10, "url": "https://my-app.theorbits.app", "terminal": [ { "kind": "cmd", "text": "text" } ], "usage": { "cpu": 1, "memory_gb": 1, "disk_gb": 1, "idle_minutes": 1 } } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## A sandbox, its usage and open ports ```http GET /v1/teams/{team}/projects/{project}/sandboxes/{sandbox} ``` The sandbox's page: its `usage` against the size's ceiling, the `terminal` output so far, and the `ports` it listens on (port 3000, team-only, in v1). Use `{sandbox}` from `GET .../sandboxes`. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `sandbox`: The sandbox's name. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "name": "seed-test-data", "runtime": "node22", "size": "small", "source": null, "state": "starting", "started_at": "2026-11-10T09:30:00Z", "stopped_at": "2026-11-10T09:30:00Z", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "stop_after": 10, "url": "https://my-app.theorbits.app", "terminal": [ { "kind": "cmd", "text": "text" } ], "usage": { "cpu": 1, "memory_gb": 1, "disk_gb": 1, "idle_minutes": 1 }, "ports": [ { "port": 3000, "url": "https://my-app.theorbits.app", "access": "team" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Delete a sandbox ```http DELETE /v1/teams/{team}/projects/{project}/sandboxes/{sandbox} ``` Terminates the machine and frees its disk. Irreversible; unlike stop, nothing is kept. **Permissions:** Owners, admins and members. Viewers get 403. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `sandbox`: The sandbox's name. Example: ```sh curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `204`: Deleted. Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Suspend a sandbox ```http POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/stop ``` Suspends the sandbox: CPU and memory are released, the disk is kept, and `start` resumes it with the work intact. The idle auto-stop does the same, so a timeout never loses work. `state` becomes `stopped`. Already stopped is a no-op 200. **Permissions:** Owners, admins and members. Viewers get 403. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `sandbox`: The sandbox's name. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/stop" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "name": "seed-test-data", "runtime": "node22", "size": "small", "source": null, "state": "starting", "started_at": "2026-11-10T09:30:00Z", "stopped_at": "2026-11-10T09:30:00Z", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "stop_after": 10, "url": "https://my-app.theorbits.app", "terminal": [ { "kind": "cmd", "text": "text" } ], "usage": { "cpu": 1, "memory_gb": 1, "disk_gb": 1, "idle_minutes": 1 } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Resume a sandbox ```http POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/start ``` Resumes a stopped sandbox from its kept disk: `state` is `starting`, then `running` (poll `GET .../sandboxes`). Counts against the team's live limit, so this returns 409 when the team is already at `SandboxPage.limit`. Already running is a no-op 200. **Permissions:** Owners, admins and members. Viewers get 403. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `sandbox`: The sandbox's name. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/start" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" ``` Response `200`: ```json { "name": "seed-test-data", "runtime": "node22", "size": "small", "source": null, "state": "starting", "started_at": "2026-11-10T09:30:00Z", "stopped_at": "2026-11-10T09:30:00Z", "started_by": { "id": "id", "name": "my-app", "email": "ada@example.com", "avatar_url": "https://my-app.theorbits.app" }, "stop_after": 10, "url": "https://my-app.theorbits.app", "terminal": [ { "kind": "cmd", "text": "text" } ], "usage": { "cpu": 1, "memory_gb": 1, "disk_gb": 1, "idle_minutes": 1 } } ``` Errors: - `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. ## A ticket to open the sandbox's terminal ```http POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket ``` A WebSocket opened by a browser can't carry the session or a bearer, so the terminal (`GET .../sandboxes/{sandbox}/terminal`) takes this ticket in its `ticket` query parameter instead. The ticket (`sbt_…`) admits the caller to this one sandbox's terminal for 60 seconds: get one right before opening the socket. It is signed, not stored, so it can't be revoked before it expires. Takes no body. The answer is never cached and the call ignores `Idempotency-Key`, so every call mints a new ticket. No plan check of its own: the sandbox must be `running` (else 409), and only Pro can start one. **Permissions:** Any team member, viewers included. A session or a `full` API token may call it (a token limited to one project only for that project); a `read` token gets 403, because this is a POST. A non-member gets 404. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. - `project`: Project slug or `prj_` id. - `sandbox`: The sandbox's name. Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/terminal-ticket" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "ticket": "sbt_eyJzIjoic2J4XzEifQ.c2lnbmF0dXJl" } ``` Errors: - `401`: Missing or invalid credentials. - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `409`: The request conflicts with current state. --- # Teams and account Source: https://docs.orbits.africa/api/teams Who a token acts as, the teams it reaches, a team's settings, overview and notifications. Call `GET /v1/me` first: it confirms the token works and lists the one team (and project, for a project-limited token) it reaches. Every other route is under `/v1/teams/{team}`, where `{team}` is the team's slug or its `team_` id. Members, invites, tokens and the team's security rules are managed in the dashboard: an API token can't reach them (see [Authentication](https://docs.orbits.africa/api/authentication)). Endpoints: - `GET /v1/me`: Current user - `GET /v1/teams`: Teams the caller belongs to - `GET /v1/teams/{team}`: Get a team - `PATCH /v1/teams/{team}`: Rename, change slug, avatar, default region, or security rules - `GET /v1/teams/{team}/overview`: Dashboard overview for a time range - `GET /v1/teams/{team}/notifications`: Notifications for the caller in this team - `POST /v1/teams/{team}/notifications`: Mark notifications read ## The team object - `id` (string, required) - `name` (string, required) - `slug` (string, required) - `avatar_url` (string or null): A path on this API (`/v1/teams/{id}/avatar?v=…`) for an uploaded avatar. - `default_region` (string) - `role` (string, required): One of `owner`, `admin`, `member`, `viewer`. - `require_two_factor` (boolean): Members without two-factor are refused on this team's routes (403). - `session_max_age_days` (integer): A member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies. - `inviters` (string): `owners`: owners and admins invite. `members`: members may too (as member or viewer only). One of `owners`, `members`. - `sign_in_methods` (array of string): How members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these. - `plan` (string, required): One of `free`, `pro`. - `billing_alert` (null or BillingAlert): The owners' billing notice (see `GET .../billing` `banner`), so the app shell can show it without another call. Null for everyone else and most of the time. - `kind` (string, required): Always `downgraded`. - `at` (string) - `amount_ngn` (integer or null) - `charge` (string): One of `automatic`, `manual`. - `grace_ends_at` (string) - `ends_at` (string) - `created_at` (string, required) ## Current user ```http GET /v1/me ``` Current user, with their teams and each team's newest projects, so the app can render its shell from one call. Token: any API token (`read` or `full`). Example: ```sh curl "https://api.theorbits.app/v1/me" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w", "email": "ada@example.com", "name": "my-app", "username": null, "avatar_url": "https://my-app.theorbits.app", "two_factor_enabled": false, "sign_in_methods": [ "github" ], "time_zone": null, "product_updates": false, "session": { "method": "email", "started_at": "2026-11-10T09:30:00Z" }, "token": { "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w", "team_id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w", "access": "full", "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "created_at": "2026-11-10T09:30:00Z" }, "teams": [ { "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "My Team", "slug": "my-app", "avatar_url": "https://my-app.theorbits.app", "default_region": "abj-1", "role": "owner", "require_two_factor": false, "session_max_age_days": 1, "inviters": "owners", "sign_in_methods": [ "email" ], "plan": "free", "billing_alert": { "kind": null, "at": null, "amount_ngn": null, "charge": null }, "created_at": "2026-11-10T09:30:00Z", "project_count": 1, "projects": [ { "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "free_address": "storefront.theorbits.app", "workload": null, "source": null, "source_kind": "git", "build": { "framework": null, "install_command": null, "build_command": null, "output_directory": null, "ignore_command": null, "changed_by": null, "changed_at": null }, "framework_version": "15", "node_version": "22.x", "region": "abj-1", "status": "pending", "paused": false, "git": { "deploy_on_push": null, "preview_pull_requests": null, "comment_on_pull_requests": null }, "preview_protection": "team_members", "production_url": "https://my-app.theorbits.app", "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "latest_deployment": null, "thumbnail_url": "https://my-app.theorbits.app", "thumbnail_color": "#7c3aed", "created_at": "2026-11-10T09:30:00Z", "updated_at": "2026-11-10T09:30:00Z" } ] } ] } ``` Errors: - `401`: Missing or invalid credentials. ## Teams the caller belongs to ```http GET /v1/teams ``` Teams the caller belongs to. Token: any API token (`read` or `full`). Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string) Example: ```sh curl "https://api.theorbits.app/v1/teams" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "next_cursor": null, "items": [ { "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "My Team", "slug": "my-app", "avatar_url": "https://my-app.theorbits.app", "default_region": "abj-1", "role": "owner", "require_two_factor": false, "session_max_age_days": 1, "inviters": "owners", "sign_in_methods": [ "email" ], "plan": "free", "billing_alert": { "kind": "upcoming", "at": "2026-11-10T09:30:00Z", "amount_ngn": null, "charge": "automatic" }, "created_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: ## Get a team ```http GET /v1/teams/{team} ``` Get a team. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "My Team", "slug": "my-app", "avatar_url": "https://my-app.theorbits.app", "default_region": "abj-1", "role": "owner", "require_two_factor": false, "session_max_age_days": 1, "inviters": "owners", "sign_in_methods": [ "email" ], "plan": "free", "billing_alert": { "kind": "upcoming", "at": "2026-11-10T09:30:00Z", "amount_ngn": null, "charge": "automatic" }, "created_at": "2026-11-10T09:30:00Z", "notifications": { "deploy.failed": { "email": "ada@example.com", "slack": false }, "deploy.live": { "email": "ada@example.com", "slack": false }, "domain.attention": { "email": "ada@example.com", "slack": false }, "member.joined": { "email": "ada@example.com", "slack": false }, "weekly": { "email": "ada@example.com", "slack": false } }, "members": [ { "user": { "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w", "email": "ada@example.com", "name": "my-app", "username": null, "avatar_url": "https://my-app.theorbits.app", "two_factor_enabled": false }, "role": "owner", "status": "active", "invite_id": "invite-id", "joined_at": "2026-11-10T09:30:00Z", "last_active_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## Rename, change slug, avatar, default region, or security rules ```http PATCH /v1/teams/{team} ``` Rename, change slug, avatar, default region, or security rules. Changing the slug breaks old dashboard links. All settings require an owner or admin. Token: a `full` API token. Path parameters: - `team`: Team slug or `team_` id. Body: - `name` (string) - `slug` (string) - `avatar_url` (string or null) - `default_region` (string): Abuja is the only region in v1. One of `abj-1`. - `require_two_factor` (boolean) - `session_max_age_days` (integer): From 1 to 365. - `inviters` (string): One of `owners`, `members`. - `sign_in_methods` (array of string): 422 when it leaves out the method the caller signed in with. - `notifications` (object): Only the switches that change, as `{"deploy.live": {"email": true}}`; the rest stay. 422 on `notifications` for an unknown event or channel. Example: ```sh curl -X PATCH "https://api.theorbits.app/v1/teams/my-team" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Team", "slug": "my-app", "avatar_url": "https://my-app.theorbits.app", "default_region": "abj-1", "require_two_factor": false, "session_max_age_days": 1, "inviters": "owners", "sign_in_methods": [ "email" ], "notifications": {} }' ``` Response `200`: ```json { "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "My Team", "slug": "my-app", "avatar_url": "https://my-app.theorbits.app", "default_region": "abj-1", "role": "owner", "require_two_factor": false, "session_max_age_days": 1, "inviters": "owners", "sign_in_methods": [ "email" ], "plan": "free", "billing_alert": { "kind": "upcoming", "at": "2026-11-10T09:30:00Z", "amount_ngn": null, "charge": "automatic" }, "created_at": "2026-11-10T09:30:00Z" } ``` Errors: - `403`: Authenticated but not allowed in this team. - `409`: The request conflicts with current state. - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Dashboard overview for a time range ```http GET /v1/teams/{team}/overview ``` Dashboard overview for a time range, worked out when asked. `deployments.total` counts deployments started in the range, and `delta_vs_previous` compares it with the range before (the 24 hours, 7 or 30 days before that). `average_build_seconds` is the mean build of those that went ready, 0 when none did. `requests.total` counts requests to any of the team's deployments, production and previews, in the range; `month_to_date` since midnight on the 1st in Lagos. Both are 0 while the log store can't be reached. `projects.failing` and `needs_attention` are the projects whose latest deployment failed. `series` cuts the range into equal slices, oldest first (7 for `24h` and `7d`, 4 for `30d`), and gives each one's deployments, average ready build (0 when none) and requests, so `series.deployments` adds up to `deployments.total`. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `range` (string): One of `24h`, `7d`, `30d`. Defaults to `24h`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/overview" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "range": "range", "logs_available": false, "projects": { "total": 1, "failing": 1 }, "deployments": { "total": 1, "delta_vs_previous": 1 }, "average_build_seconds": 1, "requests": { "total": 1, "month_to_date": 1 }, "series": { "deployments": [ 1 ], "average_build_seconds": [ 1 ], "requests": [ 1 ] }, "needs_attention": [ { "kind": "kind", "message": "message", "link": "link" } ] } ``` Errors: ## Notifications for the caller in this team ```http GET /v1/teams/{team}/notifications ``` The top bar's notifications: the team activity lines worth a nudge, newest first, with whether the caller has read each. They are a failed deployment (`deployment.failed`), a domain going live (`domain.live`) or stopping pointing at Orbits (`domain.misconfigured`), a certificate that couldn't be issued or isn't renewing (`domain.certificate.failed`), a member joining (`team.member.added`, but not the caller's own) and an alert firing (`alert.fired`). The list goes back 30 days, and no further than when the caller joined the team. `unread_count` counts the unread ones, up to 100, whatever the page. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `limit` (integer): From 1 to 50. Defaults to `20`. - `cursor` (string) - `unread` (boolean): Only the ones the caller hasn't read. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/notifications" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "next_cursor": null, "items": [ { "id": "act_01jc8x6e4mq2v7r9y3t5b0zp8w", "type": "deployment.failed", "title": "store failed to deploy", "detail": "Missing module 'mdsvex' · main", "link": "/teams/rsty-org/projects/store/deployments/dpl_1", "project": { "id": "id", "slug": "my-app", "name": "my-app" }, "read": false, "created_at": "2026-11-10T09:30:00Z" } ], "unread_count": 1 } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Mark notifications read ```http POST /v1/teams/{team}/notifications ``` Marks notifications read for the caller only. Send `ids` (from `GET /v1/teams/{team}/notifications`) for some, or `all: true` for every one up to now; with `all`, `ids` is ignored. Ids of another team's notifications are ignored. **Permissions:** Any team member, for their own notifications. A non-member gets 404. Token: a `full` API token. Send an `Idempotency-Key` header. Path parameters: - `team`: Team slug or `team_` id. Body: - `ids` (array of string): At most 100 items. - `all` (boolean) Example: ```sh curl -X POST "https://api.theorbits.app/v1/teams/my-team/notifications" \ -H "Authorization: Bearer $ORBITS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "ids" ], "all": false }' ``` Response `204`: Marked. Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. --- # Integrations Source: https://docs.orbits.africa/api/integrations The team's integrations and whether each is connected. An API token can list the team's integrations. Connecting, changing and disconnecting them (Git providers, Slack, Microsoft Teams, webhooks) holds the team's credentials with other services, so it is done in the dashboard. See [Integrations](https://docs.orbits.africa/team/integrations) and [Git](https://docs.orbits.africa/deploy/git). Endpoints: - `GET /v1/teams/{team}/integrations`: Catalog with installed state ## The integration object - `key` (string, required) - `name` (string, required) - `category` (string, required): One of `source_code`, `notifications`, `payments`, `monitoring`. - `description` (string) - `available` (boolean): False when the integration is listed but cannot be installed yet. - `installed` (boolean, required) - `status` (string or null): One of `connected`, `needs_attention`. - `summary` (string or null): One line for the Installed tab, e.g. "Repositories for shadyventures". - `scope` (string or null) - `installed_at` (string or null) - `installed_by` (null or object) - `id` (string, required) - `name` (string, required) - `fields` (array of object): Inputs needed to install. Secret values are never returned. - `name` (string, required) - `label` (string) - `secret` (boolean, required) - `projects` (array of string) ## Catalog with installed state ```http GET /v1/teams/{team}/integrations ``` The Integrations page: the Browse tab cards (name, description, Installed or Install) and the Installed tab rows (name, a one-line summary, scope, when it was installed, by whom). **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/integrations" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "key": "github", "name": "GitHub", "category": "source_code", "description": "Import repositories and deploy on every push.", "available": false, "installed": false, "status": "connected", "summary": null, "scope": "All projects", "installed_at": "2026-11-10T09:30:00Z", "installed_by": { "id": "id", "name": "my-app" }, "fields": [ { "name": "my-app", "label": "label", "secret": false } ], "projects": [ "projects" ] } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `502`: The Git providers' state could not be read. --- # Billing Source: https://docs.orbits.africa/api/billing The plans, the team's plan and what it includes, and its invoices. Read which plan a team is on, what it includes, and its invoices. Paying, cancelling and resuming happen in the dashboard, by an owner: an API token may read billing but never change it. See [Plans](https://docs.orbits.africa/billing/plans). Endpoints: - `GET /v1/plans`: The plans and their prices - `GET /v1/teams/{team}/billing`: The team's plan and billing state - `GET /v1/teams/{team}/billing/invoices`: The team's invoices - `GET /v1/teams/{team}/billing/invoices/{invoice}`: One invoice, as a receipt ## The billing object - `plan` (string, required): One of `free`, `pro`. - `status` (string, required): `past_due`: Pro, but the period has ended unpaid and the team is in its grace period. One of `free`, `active`, `past_due`. - `source` (string or null, required): `comp`: Pro granted by Orbits, nothing to pay. Null on Free. One of `flutterwave`, `comp`. - `enforced` (boolean, required): Whether plan limits are switched on. When false every feature works for every team. - `current_period` (null or object, required) - `start` (string, required) - `end` (string or null, required): Null for a plan with no end (`comp`). - `cancel_at_period_end` (boolean, required) - `grace_ends_at` (string or null, required) - `price` (object, required): Pro's price today, for the upgrade button. - `usd_cents` (integer, required) - `ngn` (integer or null, required) - `rate` (string or null, required) - `next_charge` (null or object, required) - `usd_cents` (integer, required) - `ngn` (integer or null, required) - `entitlements` (object, required): What this team may do now. All true (and `sleeps_when_idle` false) while `enforced` is false. - `functions` (boolean, required) - `sandboxes` (boolean, required) - `analytics` (boolean, required) - `speed_insights` (boolean, required) - `sleeps_when_idle` (boolean, required) - `card` (null or object, required) - `brand` (string or null, required) - `last4` (string, required) - `exp` (string or null, required) - `can_manage` (boolean, required): True for owners, who may change billing. - `banner` (null or BillingAlert, required): The owners' notice about the plan, or null. Always null for members. - `kind` (string, required): Always `downgraded`. - `at` (string) - `amount_ngn` (integer or null) - `charge` (string): One of `automatic`, `manual`. - `grace_ends_at` (string) - `ends_at` (string) ## The invoice object - `id` (string, required) - `kind` (string, required): A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due. One of `initial`, `renewal`, `manual`. - `status` (string, required): One of `open`, `paid`, `failed`, `void`. - `usd_cents` (integer, required): The dollar price. - `ngn_amount` (integer, required): Whole Naira charged: the dollar price at `fx_rate`, rounded up to a whole ₦100, locked when the invoice was made. - `fx_rate` (string, required): The USD → NGN rate it was converted at. - `period` (object or null, required): The month it paid for; null until it is paid. - `start` (string, required) - `end` (string, required) - `reference` (string, required) - `method` (string or null, required): How it was paid; null until it is. One of `card`, `bank_transfer`, `other`. - `paid_at` (string or null, required) - `created_at` (string, required) ## The plans and their prices ```http GET /v1/plans ``` Orbits has two plans. **Free** is unlimited projects, with apps that scale to zero, and without server functions, sandboxes and Analytics or Speed Insights. **Pro** is `usd_cents: 500` a month and has all of them. `ngn` is the Naira amount charged for the price: the USD price at `rate` (a rate Orbits sets, `USD → NGN`), rounded up to a whole ₦100. It is `null` until the server has a rate set (then Pro can't be bought yet). The amount a payment is actually taken for is locked on the invoice when checkout starts, so show `ngn` as "about" only if you need to hedge; `POST .../billing/checkout` refuses with 409 if the amount you showed no longer matches. `features` describe the plan, not the team, and are the same whether or not limits are being enforced yet (`enforced` on `GET /v1/teams/{team}/billing` says whether they are). Token: any API token (`read` or `full`). Example: ```sh curl "https://api.theorbits.app/v1/plans" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "free", "name": "Pro", "usd_cents": 500, "ngn": 8000, "features": { "unlimited_projects": false, "functions": false, "sandboxes": false, "analytics": false, "speed_insights": false, "sleeps_when_idle": false } } ], "rate": "1600" } ``` Errors: ## The team's plan and billing state ```http GET /v1/teams/{team}/billing ``` What the Settings Plan card and the Billing page show: the plan, whether it is `active`, `past_due` (a payment failed and the team is in its grace period) or `free`, the current period, what the next charge will be, what the plan allows, and (for owners) the card on file. `enforced` is false while Orbits has not switched plan limits on: every feature works for every team and `entitlements` all say true, although `plan` still says what the team is on. **Permissions:** Any team member sees the plan; the card is shown to owners only. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/billing" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "plan": "free", "status": "free", "source": "flutterwave", "enforced": false, "current_period": { "start": "2026-11-10T09:30:00Z", "end": "2026-11-10T09:30:00Z" }, "cancel_at_period_end": false, "grace_ends_at": "2026-11-10T09:30:00Z", "price": { "usd_cents": 1, "ngn": null, "rate": null }, "next_charge": { "usd_cents": 1, "ngn": null }, "entitlements": { "functions": false, "sandboxes": false, "analytics": false, "speed_insights": false, "sleeps_when_idle": false }, "card": { "brand": null, "last4": "4471", "exp": "09/28" }, "can_manage": false, "banner": { "kind": "upcoming", "at": "2026-11-10T09:30:00Z", "amount_ngn": null, "charge": "automatic" } } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## The team's invoices ```http GET /v1/teams/{team}/billing/invoices ``` The Invoices list: payments made for Pro, newest first. Payments that were started and never paid are not listed. `limit` is 1 to 100 (default 25); there is no cursor yet. **Permissions:** Team owners only; other members get 403. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `limit` (integer): From 1 to 100. Defaults to `25`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "items": [ { "id": "id", "kind": "initial", "status": "open", "usd_cents": 1, "ngn_amount": 1, "fx_rate": "fx-rate", "period": { "start": "2026-11-10T09:30:00Z", "end": "2026-11-10T09:30:00Z" }, "reference": "reference", "method": "card", "paid_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z" } ] } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). ## One invoice, as a receipt ```http GET /v1/teams/{team}/billing/invoices/{invoice} ``` The invoice with who paid, for which team, what for, and the card (brand and last four) it was paid with. There is no PDF; the dashboard renders the receipt. **Permissions:** Team owners only. An invoice of another team is 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. - `invoice`: An `id` from `GET .../billing/invoices`. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices/inv_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "id", "kind": "initial", "status": "open", "usd_cents": 1, "ngn_amount": 1, "fx_rate": "fx-rate", "period": { "start": "2026-11-10T09:30:00Z", "end": "2026-11-10T09:30:00Z" }, "reference": "reference", "method": "card", "paid_at": "2026-11-10T09:30:00Z", "created_at": "2026-11-10T09:30:00Z", "team": { "id": "id", "slug": "my-app", "name": "my-app" }, "payer_email": "ada@example.com", "description": "Orbits Pro", "card": { "brand": null, "last4": "last4", "exp": null } } ``` Errors: - `403`: Authenticated but not allowed in this team. - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Usage, activity and operations Source: https://docs.orbits.africa/api/usage-and-activity What a team used, its activity feed, and the operations slow changes return. `GET .../usage` is what the team used in a period; `GET .../activity` is the feed of what happened, kept 90 days. A change that takes time answers `202` with an operation: poll `GET /v1/operations/{operation}` until its `state` is `succeeded` or `failed`. Endpoints: - `GET /v1/teams/{team}/usage`: A month of the team's usage, by day and by project - `GET /v1/teams/{team}/activity`: Team activity feed - `GET /v1/operations/{operation}`: Poll an asynchronous operation ## The usage object - `logs_available` (boolean, required): False while the log store can't be reached: requests, bandwidth and function runs are then zeros, not a quiet month; builds and deployments still count. Show the log figures as unavailable. - `month` (string, required) - `current` (boolean, required): This month, so the series stops at today. - `months` (array of string, required): From the team's first deployment to now, newest first. - `days` (array of string, required): The month's days so far. - `totals` (UsageTotals, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `deleted_projects` (object, required): Usage of projects deleted since, which `totals` includes and `by_project` doesn't; zeros when there is none. - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `previous` (object or null, required): The same days of the month before; null when the team had no deployments before this month. - `month` (string, required) - `totals` (UsageTotals, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `daily` (array of UsageDay, required) - `date` (string, required) - `totals` (UsageTotals, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `by_project` (array of object, required): Every project the team has, most requests first. A deleted project's usage counts in the totals only. - `project_id` (string, required) - `slug` (string, required) - `name` (string, required) - `totals` (UsageTotals, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `previous` (UsageTotals or null, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `daily` (array of UsageDay, required) - `date` (string, required) - `totals` (UsageTotals, required) - `requests` (integer, required) - `bandwidth_bytes` (integer, required) - `build_minutes` (number, required): One decimal place. - `function_runs` (integer, required) - `deployments` (integer, required) - `log_lines` (integer, required) - `by_environment` (object, required): Keyed by `production`, `preview` or `development`, for those with usage. - `preview_branches` (integer, required): Branches with a preview deployment this month. ## The activity object - `id` (string, required) - `type` (string, required): The event it was written from. - `category` (string, required): What a line is about, as the Activity page's type filter groups them. `domains` has no lines yet. One of `deployments`, `domains`, `members`, `variables`, `integrations`, `projects`, `team`. - `actor` (object, required): Who did it: a member (`user`), a commit's author for a push (`git`, no `user_id`), or Orbits itself (`system`). - `kind` (string, required): One of `user`, `system`, `git`. - `user_id` (string or null, required) - `name` (string, required) - `summary` (string, required): The whole sentence, ready to show. - `project_id` (string or null, required) - `project` (object or null, required): The project it's about, as it was named then. - `id` (string, required) - `slug` (string, required) - `name` (string, required) - `deployment_id` (string or null, required): The deployment it's about, for a link to its page. - `failed` (boolean, required): A build that failed: the page shows the line in red. - `created_at` (string, required) ## The operation object - `id` (string, required) - `kind` (string, required) - `state` (string, required): One of `pending`, `running`, `succeeded`, `failed`. - `resource` (string) - `created_at` (string, required) - `finished_at` (string or null) - `error` (null or Problem) - `type` (string, required) - `title` (string, required) - `status` (integer, required) - `detail` (string) - `instance` (string) - `request_id` (string) - `code` (string): A stable reason, where one is defined: `plan_required` (402); `price_changed` and `already_pro` (409) and `billing_unavailable` (503) from billing. - `required_plan` (string): On a 402: the plan that includes what was asked for. One of `pro`. - `feature` (string): On a 402: what the plan lacks. One of `functions`, `sandboxes`, `analytics`, `speed_insights`. - `errors` (array of object) - `field` (string, required) - `message` (string, required) ## A month of the team's usage, by day and by project ```http GET /v1/teams/{team}/usage ``` The team's Usage page and its CSV, a project's Usage page (its `by_project` row), and the overview's usage panel. Days are Lagos days. `requests`, `bandwidth_bytes` (bytes the edge sent, headers included) and `log_lines` come from a daily rollup of the runtime logs kept 400 days; bandwidth is counted from when the edge started recording it, so earlier requests count 0 bytes. `build_minutes` (start to finish of each build, failed ones included) and `deployments` count deployments by the day they were created, back to the team's first. `function_runs` counts requests to projects with a `function` workload (also in `requests`): each is a call to the function, though functions run as one long-lived server until a per-call runtime ships. Figures for today are as of the call. `previous` is the same days of the month before, for "+18% on September", or null when the team had no deployments before this month. `months` lists every month from the team's first deployment to now, newest first. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `month` (string): Defaults to this month. A month still to come is 422. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/usage" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "logs_available": false, "month": "2026-10", "current": false, "months": [ "months" ], "days": [ "2026-11-10" ], "totals": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 }, "deleted_projects": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 }, "previous": { "month": "month", "totals": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 } }, "daily": [ { "date": "2026-11-10", "totals": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 } } ], "by_project": [ { "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app", "totals": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 }, "previous": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 }, "daily": [ { "date": "2026-11-10", "totals": { "requests": 1, "bandwidth_bytes": 1, "build_minutes": 1, "function_runs": 1, "deployments": 1, "log_lines": 1 } } ], "by_environment": {}, "preview_branches": 1 } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Team activity feed ```http GET /v1/teams/{team}/activity ``` The team's Activity page and its export: what happened across the team, newest first, one sentence each. Deployments (a preview started, production deployed, promoted or rolled back, a build failed), environment variables (added, updated, removed, restored, revealed, pulled), projects (created, renamed, settings changed, paused, deleted, moved in), members (joined, left, role changed), team settings and integrations (GitHub connected or disconnected). Invites and domains aren't in it yet. Lines are written from the platform's events a moment after they happen, kept 90 days, and read as they did then: a project or member renamed since keeps its old name in older lines. **Permissions:** Any team member. A non-member gets 404. Token: any API token (`read` or `full`). Path parameters: - `team`: Team slug or `team_` id. Query parameters: - `q` (string): Matches the sentence, the actor's name or the project's name, in any case. At most 200 characters. - `actor` (string): A person's `id` from `people`. - `project` (string): A project's `id` or `slug`. - `type` (string): One `ActivityCategory`, or several separated by commas. - `since` (string): Oldest line to return; defaults to 7 days ago, and is clamped to 90 days ago. - `limit` (integer): From 1 to 100. Defaults to `25`. - `cursor` (string): `next_cursor` from the previous page. Example: ```sh curl "https://api.theorbits.app/v1/teams/my-team/activity" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "as_of": "2026-11-10T09:30:00Z", "items": [ { "id": "act_0193a1f2-6c1e-7d2a-9b3f-1e2d3c4b5a69", "type": "project.production.changed", "category": "deployments", "actor": { "kind": "user", "user_id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w", "name": "my-app" }, "summary": "Ada promoted a1f9c2e to production", "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w", "project": { "id": "act_01jc8x6e4mq2v7r9y3t5b0zp8w", "slug": "my-app", "name": "my-app" }, "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w", "failed": false, "created_at": "2026-11-10T09:30:00Z" } ], "total": 1, "total_capped": false, "next_cursor": null, "any": false, "people": [ { "id": "id", "name": "my-app" } ], "projects": [ { "id": "id", "slug": "my-app", "name": "my-app" } ] } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). - `422`: Validation failed, or the Idempotency-Key was reused with a different body. ## Poll an asynchronous operation ```http GET /v1/operations/{operation} ``` Poll an asynchronous operation. **Permissions:** The starter of the operation or an owner or admin of the team it ran in. Token: any API token (`read` or `full`). Path parameters: - `operation` Example: ```sh curl "https://api.theorbits.app/v1/operations/op_01jc8x6e4mq2v7r9y3t5b0zp8w" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` Response `200`: ```json { "id": "op_01jc8x6e4mq2v7r9y3t5b0zp8w", "kind": "team.delete", "state": "pending", "resource": "resource", "created_at": "2026-11-10T09:30:00Z", "finished_at": "2026-11-10T09:30:00Z", "error": { "type": "https://my-app.theorbits.app", "title": "title", "status": 1, "detail": "detail", "instance": "instance", "request_id": "request-id", "code": "code", "required_plan": "pro", "feature": "functions", "errors": [ { "field": "field", "message": "message" } ] } } ``` Errors: - `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose). --- # Deploy your first project Source: https://docs.orbits.africa/getting-started/quickstart From a new account to a live site in a few minutes. You sign up, connect GitHub, GitLab or Bitbucket, import a repository and deploy it to its own address on theorbits.app. Orbits builds your code and runs it in Abuja. Connect a Git repository once, and every push after that deploys on its own. This page takes you from nothing to a live URL. ## 1. Sign up Go to [orbits.africa/signup](https://orbits.africa/signup). There are two ways in: - **With your email.** Enter your full name and work email and press **Create account**. Orbits emails you a sign-in link: open the email from Orbits and click **Sign in to Orbits**. The link works once and expires in 15 minutes. If it has expired, ask for another from the same page. - **With GitHub, GitLab or Bitbucket.** Pick the provider, approve Orbits on its consent screen, and you come straight back signed in. Orbits needs a verified email address on the provider account. If that email already has an Orbits account, the provider is linked to it rather than making a second account. There is no password. Next time, sign in at [orbits.africa/login](https://orbits.africa/login) the same way: **Continue with email**, or the provider you used. If your account has two-factor authentication on, Orbits asks for a code from your authenticator app after the link or provider step. See [security](https://docs.orbits.africa/team/security). ## 2. Create your team Everything in Orbits belongs to a team: projects, domains, variables and billing. On **Create your team**, give it a **Team name** and a **Team URL** (the part after `orbits.africa/`). You can invite teammates by email now under **Invite teammates**, or later from Members. Then press **Create team**. Read more about teams, roles and the rest of the vocabulary in [concepts](https://docs.orbits.africa/getting-started/concepts). ## 3. Connect a Git provider Open **New project**. The **Import a Git repository** step has a tab for each provider. Pick yours and press **Continue to GitHub** (or **Continue to GitLab**, **Continue to Bitbucket**). ::::tabs :::tab[GitHub] Orbits uses a GitHub App. On GitHub, pick the account or organisation and which repositories Orbits can see, then you come back to Orbits. You can change the repository list later on GitHub; the GitHub integration page links to it as **Change on GitHub**. ::: :::tab[GitLab] Orbits connects to GitLab.com with your OAuth consent, asking for the `api` and `read_repository` scopes. It lists the GitLab projects where you are Maintainer or above, because it needs to add a webhook to the one you import. ::: :::tab[Bitbucket] Orbits connects to Bitbucket Cloud with your OAuth consent. It lists the repositories you administer, in every workspace you belong to. ::: :::: Only team owners and admins can connect a provider. Self-managed GitLab is not available yet. For details on each provider, see [deploying from Git](https://docs.orbits.africa/deploy/git). ## 4. Import a repository The list shows the repositories Orbits can see, newest push first, each with the framework Orbits detected. Press **Import** next to the one you want. A repository already used by a project says so and offers to open it. If a repository is missing, its provider connection can't see it: on GitHub, add it to the App's repository access. ## 5. Configure The **Configure** step is filled in from the repository. Orbits reads `package.json` and the lock file, says what it found ("Detected from package.json and the lock file"), and you change anything that looks wrong. | Field | What it is | | --- | --- | | **Name** | The project's name. It also becomes its address, shown under **Address**: `.theorbits.app`. The address is unique across Orbits, so a taken name asks for another. | | **Region** | Abuja (`abj-1`), the only region. See [region](https://docs.orbits.africa/getting-started/region). | | **Production branch** | Pushes here go to production; other branches get previews. It starts as the repository's default branch. | | **Root directory** | Where the app lives in the repository. `./` is the root. | | **Framework** | What Orbits detected, or pick one. See [frameworks](https://docs.orbits.africa/deploy/frameworks). | | **Install command**, **Build command**, **Output directory** | Prefilled from the detection. Leave them as they are unless your build needs something different. See [build settings](https://docs.orbits.africa/deploy/build-settings). | | **Environment variables** | Variables the app needs, used by Production and Preview. Add them one by one, or press **Import .env** to read a `.env` file. You can change them later. | ### Monorepos When the repository root holds several apps (a Turborepo, Nx, Lerna, Rush, pnpm or npm, Yarn or Bun workspaces, or plain folders such as `web/` beside `server/`), Orbits lists the apps it found under **App** and waits for you to pick one. Picking an app sets the root directory and reads that app's settings. If yours isn't listed, edit the root directory by hand. Import the same repository again, with another root directory, for each app you want to deploy. In a monorepo every push builds every project made from the repository, even a push that only changes another app. To skip those builds, set **Skip a build when** in the project's settings afterwards ([ignored build step](https://docs.orbits.africa/deploy/build-settings#ignored-build-step)). ## 6. Deploy Press **Deploy**. The page follows the build as it happens: Queued, Cloning repository, Installing packages, Building, Uploading and Going live, with the build log underneath. You can leave the page; the build keeps running and shows up under Deployments. **Cancel deployment** stops it, and nothing goes live. If the build fails, the page says what went wrong and where, and nothing went live. Fix the code or the settings and push again, or redeploy from the project. When it's ready, the page shows your production address: ```console $ curl -I https://storefront.theorbits.app HTTP/2 200 ``` Every project gets `https://.theorbits.app` for free, with a certificate. A few seconds after the deployment is live, Orbits takes a screenshot of the home page for the project card. ## What happens on each push From now on you don't need the dashboard to deploy: - A push to the **production branch** builds a new production deployment. Production keeps serving the current one until the new build is ready, then switches over. - A push to **any other branch** builds a preview, with its own address. See [previews](https://docs.orbits.africa/deploy/previews). - On GitHub, GitLab and Bitbucket, each commit shows a status, `Orbits – `: pending while it builds, then passed or failed. You can turn deploy-on-push and previews off in the project's settings under Git. ## Next steps ::::cards :::card[Add your own domain]{href=/domains/custom-domains} Serve the project on a domain you own, with a certificate Orbits issues and renews. ::: :::card[Set environment variables]{href=/deploy/environment-variables} Keys and secrets per environment, encrypted, and how to apply a change. ::: :::card[Work with deployments]{href=/deploy/deployments} Promote a preview, roll back production, redeploy, and read build logs. ::: :::card[Deploy without Git]{href=/getting-started/upload-a-folder} Send a folder from your machine with the CLI. ::: :::: --- # Deploy a folder without Git Source: https://docs.orbits.africa/getting-started/upload-a-folder Deploy a project that has no repository by sending its folder as a zip. Orbits builds it like any other deployment and keeps the last five uploads for redeploys. Not every project lives in Git. An **upload project** has no repository: its source is a zip of a folder you send, and Orbits unpacks it in place of a Git clone, then detects the framework, installs, builds and serves it exactly as it would a repository. It works for any kind of project, not only static sites: a Vite app, a Next.js app or a Node server are built the same way. The quickest way to send a folder is the [Orbits CLI](https://docs.orbits.africa/cli). ## Deploy with the CLI Install the CLI and sign in once: ```console $ curl -fsSL https://orbits.africa/install | bash $ orbits login ``` `orbits login` opens the web app in your browser, where you choose the team and the access, and the CLI receives an API token for that team. Then, in your project's folder, make an upload project and deploy: ```console $ cd my-site $ orbits link --create $ orbits deploy ✓ Packed 14 files 48 KB ✓ Uploaded 48 KB ✓ Queued 1s ✓ Installing 6s ✓ Building 12s ✓ Going live 2s ✓ Ready in 23s (production) https://my-site.theorbits.app ``` `orbits link --create` makes a new upload project named after the folder and writes `.orbits/project.json` so later commands know which project the folder is (it also adds `.orbits` to `.gitignore`). `orbits link` without `--create` lets you pick an existing project instead. `orbits deploy` deploys the current folder; `orbits deploy ./dist` deploys another one. While it builds, the CLI shows each step and the build log. When it's ready it prints the address on standard output, so a script can capture it: ```console $ url=$(orbits deploy --no-logs) ``` Uploads always go to **production**. There is no preview for an upload. ## What goes in the zip Send the project's files: `package.json`, the source and its config, exactly as you would commit them. Orbits builds from source, so you don't need to build first (though a folder of plain HTML with an `index.html` is served as it is). These are left out, at any depth, whether the CLI packs the folder or you zip it yourself: - `node_modules`, `.git`, `.next`, `__MACOSX` and `.DS_Store` The CLI also leaves out `.orbits`, `.env.local` and `.env.*.local`, and anything matching the patterns in a `.orbitsignore` file in the folder (it uses `.gitignore` syntax). If the zip holds a single top-level folder, Orbits strips it, so zipping the folder or zipping its contents both work. Links and special files are refused. ## Limits | | Limit | | --- | --- | | Zip size | 100 MiB (104,857,600 bytes) | | Unpacked size | 500 MiB | | Files and folders, unpacked | 20,000 entries (folders the zip lists count as well as files; what is left out doesn't count) | | Unfinished uploads per team | 5 at a time | A zip over a limit fails on the Cloning repository step, with the reason in the build log. ## Redeploy and roll back Orbits keeps the archives of a project's **last five** uploads. - **Redeploy** rebuilds a deployment from its stored archive. A deployment older than the last five has no archive left, and Orbits says so: send the folder again. - **Roll back** points production at an earlier build without building anything, so it works whatever the archive's age, within the last three production builds. See [deployments](https://docs.orbits.africa/deploy/deployments) for both. ## Environment variables An upload project has environment variables like any other. Set them in the web app or with `orbits env add`, then deploy again: variables apply to deployments made after the change. See [environment variables](https://docs.orbits.africa/deploy/environment-variables). ## In CI Make a token under **Team › Settings › API tokens** with full access, then: ```console $ export ORBITS_TOKEN=orb_live_… $ orbits --project my-site deploy ./dist --no-logs ``` A failed build exits with code 5, so the job fails with it. ## Through the API The CLI uses the public API, and so can you: start an upload, send the zip to the presigned URL it returns, then complete the upload, which queues the production deployment. The steps and fields are in [the deployments API](https://docs.orbits.africa/api/deployments). :::note An upload project can't be switched to deploy from a repository later. To move to Git, import the repository as a new project. ::: --- # How Orbits fits together Source: https://docs.orbits.africa/getting-started/concepts Teams, members and roles, projects, deployments, environments, domains and operations, and the IDs that name them. A few words come up on every page of these docs. This is what each one means in Orbits. ## Teams A **team** owns everything: its projects, domains, environment variables, Git connections, API tokens and its plan. You can belong to several teams and switch between them; each has its own URL in the web app, `orbits.africa/`. A team's plan is Free or Pro, and billing belongs to the team, not to a person. See [plans](https://docs.orbits.africa/billing/plans). ## Members and roles Everyone in a team has one role. | Role | Can | | --- | --- | | **Owner** | Everything, including billing, deleting the team and granting or removing owners and admins. A team always has at least one owner. | | **Admin** | Change project and team settings, connect Git providers, pause, transfer and delete projects, manage API tokens. | | **Member** | Create projects, deploy, redeploy, promote and roll back, cancel builds, change environment variables, add domains and DNS records. | | **Viewer** | Read: projects, deployments, logs, domains, and variable keys (never their values). | Someone who isn't in a team can't see that it exists: its pages answer "not found". Inviting people and changing roles are on [teams and roles](https://docs.orbits.africa/team/teams-and-roles). ## Projects A **project** is one app: one repository (or one folder, for an [upload project](https://docs.orbits.africa/getting-started/upload-a-folder)), one set of build settings, and one production site. A monorepo with three apps is three projects made from the same repository, each with its own root directory. Each project has: - a **name** and a **slug**, its name in lower case with hyphens. The slug is unique across all of Orbits, because it is the project's free address, `.theorbits.app`. - a **workload**: how it runs (a static site, a server app, a worker...). It is set when the project is created and doesn't change. See [frameworks](https://docs.orbits.africa/deploy/frameworks). - a **region**, always Abuja (`abj-1`). Project settings are on [projects](https://docs.orbits.africa/deploy/projects). ## Deployments A **deployment** is one build of one commit, and it never changes once it is built. Pushing again, changing a variable or changing a setting makes a new deployment; it never edits an old one. Every deployment is in one of two environments: - **Production**: built from the production branch (or promoted to it). One production deployment is *current*: it is what your project's addresses serve. - **Preview**: built from any other branch, for checking a change before it reaches production. Each gets its own address. Because deployments are immutable, changing what production serves is a matter of moving a pointer: - **Promote** takes a ready preview's commit, builds it with production's variables, and makes the new build current when it's ready. - **Roll back** points production at an earlier production build straight away, with nothing rebuilt. A deployment moves through the states `queued`, `building`, then `ready`, `failed` or `canceled`. See [deployments](https://docs.orbits.africa/deploy/deployments). ## Environments Environment variables are scoped to three **environments**: | Environment | Used by | | --- | --- | | **Production** | Production deployments. | | **Preview** | Preview deployments. | | **Development** | Your own machine: the values `orbits env pull` writes to `.env.local`. No deployment runs in it. | A variable can apply to any mix of them. See [environment variables](https://docs.orbits.africa/deploy/environment-variables). ## Domains Every project answers on its free address, `.theorbits.app`. A **domain** is a name you own, such as `shop.example.com`, added to the team and pointed at a project's production, at a branch's newest preview, or set to redirect somewhere else. Domains belong to the team, so they appear on the team's **Domains and DNS** page and on the Domains page of the project they serve. Orbits issues and renews their certificates. See [domains](https://docs.orbits.africa/domains/overview). ## Operations Most things answer at once. A few take longer, such as deleting a project or a team, or moving a project to another team. Those return an **operation**: a record with its own ID whose state goes `pending`, `running`, then `succeeded` or `failed`. The web app waits for it; through the [API](https://docs.orbits.africa/api/conventions) you poll it until it finishes. ## IDs Every object has an ID with a prefix that says what it is. You'll see them in the API, the CLI's `--json` output and in URLs. | Prefix | Object | | --- | --- | | `usr_` | A person | | `team_` | A team | | `prj_` | A project | | `dpl_` | A deployment | | `dom_` | A domain | | `rec_` | A DNS record | | `tok_` | An API token | | `op_` | An operation | Wherever the API takes a team or a project, it accepts its slug as well as its ID. --- # Where your apps run Source: https://docs.orbits.africa/getting-started/region Orbits has one region, Abuja in Nigeria (abj-1). Every build and every app runs there. Orbits runs in one region: **Abuja, Nigeria**, with the code `abj-1`. There are no other regions, and no choice to make. The **Region** field on New project and in a project's settings shows Abuja (`abj-1`), and it is the only value the API accepts for a project or a team. ## What runs there - **Builds.** Your code is cloned, installed and built in Abuja. - **Apps.** Production and preview deployments run in Abuja, and their addresses, free (`theorbits.app`) and custom, are served from there. - **Orbits DNS.** If you hand a domain's DNS to Orbits, its nameservers answer from there too. ## What it means for latency Visitors reach your app over the internet from wherever they are, and every request travels to Abuja and back. For visitors in Nigeria and West Africa that is a short trip. Visitors further away see the extra distance on every request that reaches the app. A few things help: - Keep the app close to its data. If your app talks to a database, put the database near Abuja, so each request doesn't make several long trips. - Let browsers cache what doesn't change. Fingerprinted assets (a framework's built JavaScript and CSS) can carry long cache lifetimes, so a returning visitor doesn't fetch them again. - Watch real numbers. [Speed Insights](https://docs.orbits.africa/observe/speed-insights) reports Web Vitals from your visitors' browsers, and [observability](https://docs.orbits.africa/observe/observability) shows request durations as the app sees them. ## Using the region in the API and CLI Projects and teams carry their region as `abj-1`: ```json title="Project (excerpt)" { "slug": "storefront", "region": "abj-1", "free_address": "storefront.theorbits.app" } ``` You don't need to send it when you create a project: it defaults to `abj-1`, and any other value is refused. :::info[No Lagos region] Some early screens showed a Lagos region. It doesn't exist: Abuja is the only region. ::: --- # Deploy from Git Source: https://docs.orbits.africa/deploy/git Connect GitHub, GitLab.com or Bitbucket Cloud to a team, deploy on every push, get previews for pull requests, and see each build's status on the commit. A team connects its Git provider once, under **Integrations** or from the Import step of **New project**. After that, any project imported from that provider deploys on every push. Connecting and disconnecting are for owners and admins. ## Providers | | GitHub | GitLab.com | Bitbucket Cloud | | --- | --- | --- | --- | | How it connects | The Orbits GitHub App, installed on an account or organisation | Your OAuth consent | Your OAuth consent | | Deploy on push | Yes | Yes | Yes | | Previews for branches and pull or merge requests | Yes | Yes | Yes | | Commit status `Orbits – ` | Yes | Yes | Yes | | Repository website set to the free address | Yes | No | No | | "Ready to deploy" email for new repositories | Yes | No | No | Self-managed GitLab is not available yet, and neither is GitBucket (it shows as **Soon**). ## Connect GitHub Press **Continue to GitHub**. GitHub shows its own screen: pick the account or organisation and the repositories Orbits may see (all, or only selected ones), then GitHub sends you back to Orbits. The App reads your code, adds webhooks and reports statuses. To change which repositories Orbits can see later, use **Change on GitHub** on the GitHub integration page. A team has one GitHub installation. The integration page shows the connected account, how many repositories Orbits can see, and how many webhook deliveries arrived this month. ## Connect GitLab or Bitbucket Press **Continue to GitLab** or **Continue to Bitbucket**, approve Orbits on the provider, and you come back to Orbits. - **GitLab** asks for the `api` and `read_repository` scopes. Orbits lists the GitLab projects where you are Maintainer or above, since it adds a webhook to each project you import. Projects in subgroups keep their full path, such as `group/subgroup/app`. - **Bitbucket** shows the Orbits app's permissions: your account, repositories and pull requests (read), and webhooks (read and write). Orbits lists the repositories you administer, in every workspace you belong to. The connection is **the grant of the person who connected it**: Orbits acts as them. If that person revokes Orbits on the provider, or loses access to the repositories, the connection shows **needs attention** and pushes stop deploying. Someone with access connects again to repair it. The integration page's link to the provider shows where that person can see or revoke Orbits' access. When you import a repository, Orbits adds a webhook to it. If the connected person can't add one there, the import is refused. ## Deploy on push With a project imported, each push decides what to build: - A push to the **production branch** builds a production deployment, which goes live when it's ready. - A push to **any other branch** builds a preview of that branch, when previews are on. Both are project settings, under **Git** in the project's settings: | Setting | What it does | | --- | --- | | **Production branch** | The branch that deploys to production. | | **Deploy every push** | Off, pushes build nothing; you deploy by hand. | | **Preview pull requests** | Off, only the production branch builds. | | **Comment on pull requests** | Stored, but posting the preview link on the pull request is not available yet. | When a branch has an open pull request (a merge request on GitLab), its previews carry the pull request's number. See [previews](https://docs.orbits.africa/deploy/previews). The same commit is never built twice at once: a push of a commit that is already queued or building is skipped. ## Commit statuses Every deployment of a project from Git sets a status on its commit, named `Orbits – ` and linked to the deployment's page in the web app: | Deployment | Status on the commit | | --- | --- | | Queued or building | Pending: "Queued", "Building" | | Ready | Success: "Preview ready" or "Deployed to production" | | Failed | Failure: "Build failed" | | Canceled | Error: "Canceled" | A status only ever moves forward, so a late update never puts an old state back. You can turn statuses off with **Report deploy status as a check** on the integration page. ## Repository website on GitHub When a production deployment of a GitHub project goes live, Orbits sets the repository's **Website** (in its About box on GitHub) to `https://.theorbits.app`. It only replaces a website that is empty or already a `theorbits.app` address, so a website you set yourself stays. A custom domain doesn't replace the free address there yet. **Report deploy status as a check** turns this off too. ## "Ready to deploy" email On GitHub, when someone pushes to the default branch of a repository created in the last seven days that no project uses yet, and Orbits detects a framework in it, the team gets one email suggesting it be deployed. It goes to the team member whose email matches the pusher's, or else to the team's owners. Pushes by bots don't count. Orbits only hears about repositories the GitHub App can see: an installation limited to selected repositories doesn't send this for a new repository until you add it. ## Pull-request settings The integration page of each provider has three switches under **Pull requests** (merge requests on GitLab). They save as you change them, and only owners and admins can change them. | Switch | What it does | | --- | --- | | **Comment with a preview link** | Not available yet: Orbits doesn't post comments on pull requests. | | **Report deploy status as a check** | Commit statuses, and on GitHub the repository website. On by default. | | **Build pull requests from forks** | Forks' pull requests are ignored unless this is on. Leave it off unless you trust every contributor: a fork's build could read your preview environment variables. | ## Disconnect a provider Press **Disconnect** on the integration page. The dialog says how many projects stop deploying on push. - **GitHub:** Orbits forgets the installation and uninstalls its GitHub App from the account. - **GitLab and Bitbucket:** Orbits forgets the connected person's grant and removes the webhooks it added, as far as the provider still allows. The grant stays listed on the provider until that person revokes it there. What keeps working: existing deployments, production and its domains. Your sites stay online. What stops: deploying on push, previews and pull-request statuses, until you connect the provider again. Deleting a team disconnects its Git providers first. ## Troubleshooting **A repository isn't in the list.** On GitHub, the App can't see it: add it to the installation. On GitLab you need Maintainer or above on the project; on Bitbucket, admin on the repository. The list holds up to 500 repositories. **Pushes stopped deploying.** Check the integration page: **needs attention** means connect again. Check the project's **Deploy every push** setting, and that the push was to a branch Orbits builds. After a [rollback](https://docs.orbits.africa/deploy/deployments#roll-back), production pushes still build but don't go live until you turn auto-deploy back on. The API for all of this is in [integrations](https://docs.orbits.africa/api/integrations). --- # Frameworks and workloads Source: https://docs.orbits.africa/deploy/frameworks Which frameworks Orbits detects, the commands it uses for each, and how each kind of project runs, from static sites to Node servers, workers and containers. Orbits reads your repository's `package.json`, lock file and a few config files to work out what the app is and how to build it. What it finds fills in the Configure step, and you can change any of it. ## Detected frameworks Detection checks the dependencies in `package.json` in this order, so a Next.js app that also lists Vite is still Next.js: | Framework | Detected by | Default output | Runs as | | --- | --- | --- | --- | | Next.js | `next` | `.next` (`out` with `output: "export"`) | Server (`next start`), or static files for a static export | | Nuxt | `nuxt` | `.output` | Server | | Astro | `astro` | `dist` | Static files, or a server when the Node adapter writes one | | SvelteKit | `@sveltejs/kit` | `.svelte-kit` | Server (needs `@sveltejs/adapter-node`) | | Remix | any `@remix-run/` package | `build` | Server | | React Router | `@react-router/dev` | | Server | | SolidStart | `@solidjs/start` | | Server | | TanStack Start | `@tanstack/react-start` | | Server | | Gatsby | `gatsby` | `public` | Static files | | Create React App | `react-scripts` | `build` | Static files | | Vite | `vite` | `dist` | Static files | | Node.js | `express`, `fastify`, `koa`, `hono` or `@nestjs/core`, or a `start` script | | Server | | Dolph.js | `@dolphjs/dolph` | | Server | | HTML | no `package.json`, an `index.html` | the root | Static files | Elysia isn't detected from the repository, but you can pick it as the framework on the Configure step. Anything else with a `package.json` and no `start` script is built and served as a static site. Detection also reports the Node.js version the repository asks for, from `engines.node` in `package.json`, or from `.nvmrc` or `.node-version`. Check that the project's **Node.js version** setting matches it (see [Node.js versions](#nodejs-versions)). ## Install and build commands The package manager comes from the lock file, or from the `packageManager` field when there is none: | Lock file | Install | Build | | --- | --- | --- | | `pnpm-lock.yaml` | `pnpm install --frozen-lockfile` | `pnpm build` | | `yarn.lock` | `yarn install --frozen-lockfile` (`yarn install --immutable` on Yarn 2 and later) | `yarn build` | | `bun.lock` | `bun install --frozen-lockfile` | `bun run build` | | `bun.lockb` | `bun install` | `bun run build` | | `package-lock.json` | `npm ci` | `npm run build` | | none | `npm install` | `npm run build` | The build command runs your `build` script, so it's only set when `package.json` has one. A Next.js app with no `build` script runs `next build`. A static site with no `build` script is served as it is, with no install. In a monorepo, the lock file and `packageManager` field are looked for in the app's directory and every directory above it up to the repository root. Bun can install and build any project. A server app whose start command uses Bun also runs with Bun; otherwise apps run on Node.js. ## Workloads Each project has a **workload**, the way it runs. It's chosen when the project is created and can't change afterwards. | Workload | What it is | How Orbits runs it | | --- | --- | --- | | `static` | Files: HTML, CSS, JavaScript, images | Served as they are from the output directory. Unknown paths answer 404, unless the SPA fallback is on, in which case they answer with `index.html`. | | `function` | A server-rendered framework | Runs the framework's server, the same way as `app`. Pro only. | | `app` | A long-running Node.js (or Bun) server | Started with its start command, listening on port 3000 unless the project sets another port. | | `worker` | A command with no web traffic | Runs its command, continuously or on a cron schedule. | | `container` | Your own image | Built from the repository's Dockerfile, or pulled from a prebuilt image, and run on the port you set. | When you don't choose one, Orbits picks it from the framework: Next.js, SvelteKit, Nuxt, Remix, React Router, SolidStart and TanStack Start get `function`; Node.js, Elysia and Dolph.js get `app`; everything else gets `static`. The web app's Configure step doesn't ask: it uses this default. To create a `worker` or `container` project, set the workload when you create it [through the API](https://docs.orbits.africa/api/projects). :::note[On Free, server frameworks run as apps] The `function` workload is part of Pro. On Free, a framework that would default to `function` (Next.js, SvelteKit, Nuxt, Remix and the like) is created as an always-on `app` on port 3000 instead; it builds and runs the same way. Asking for `function` explicitly on Free is refused. See [plans](https://docs.orbits.africa/billing/plans). ::: ### Server apps For a server app, Orbits finds the start command in this order: 1. the start command the project sets; 2. the server a framework's build wrote: `.output/server/index.mjs` (Nuxt, SolidStart, TanStack Start), `dist/server/entry.mjs` (Astro's Node adapter), `build/index.js` (SvelteKit's Node adapter); 3. `npm run start`, when `package.json` has a `start` script. If none applies, the build fails at Uploading and says to add a `start` script. A SvelteKit app needs `@sveltejs/adapter-node`, so the build has a server to run. The app is started with `NODE_ENV=production` and `PORT`, `HOST=0.0.0.0` and `HOSTNAME=0.0.0.0` set, which are what Next.js, Nitro, SvelteKit, Astro and Express listen on by convention. Listen on `PORT`. Two cases change how a project runs whatever its workload says: - A Next.js app built with `output: "export"` is served as a static site from `out`, because `next start` can't serve a static export. - An Astro build that writes a server (`dist/server/entry.mjs`) runs on Node. ### Workers A worker runs the command the project sets, and needs one: a worker without a command fails at Installing. With a schedule, it's a cron expression read in UTC. Workers run for production only; a preview of a worker is started, checked and stopped. ### Containers A `container` project is built from its Dockerfile (the path is a project setting) or runs a prebuilt image you name, but not both. It needs the port it listens on, or the build fails. Your image runs as whatever user it sets. ## Node.js versions Builds and apps use Node.js 22 unless the project asks for another. Node.js 18, 20, 22 and 24 are available. Pick 18, 20 or 22 with **Node.js version** in the project's settings, or set `node_version` (such as `24.x`) [through the API](https://docs.orbits.africa/api/projects). A version Orbits doesn't have builds on Node.js 22. ## Not available yet - WebSockets: requests reach your app as plain HTTP, without the upgrade to a WebSocket. - Apps that sleep when idle: every app stays running, on Free and on Pro. - Creating a project from a template. For the build settings themselves, see [build settings](https://docs.orbits.africa/deploy/build-settings). --- # Build settings Source: https://docs.orbits.africa/deploy/build-settings The install, build and output settings, the root directory, the Node.js version, skipping builds with an ignored build step, the build cache, and the warnings a deployment can carry. Orbits fills in a project's build settings from what it [detects](https://docs.orbits.africa/deploy/frameworks) when you import the repository. You change them on the Configure step, or later in the project's **Settings** under **Build** ("Orbits found these in package.json. Change them only if your build needs something different."). Changes apply from the **next** deployment. Deployments already built keep the settings they were built with: [redeploy](https://docs.orbits.africa/deploy/deployments#redeploy) to rebuild with the new ones. Changing settings is for owners and admins. ## The settings | Setting | What it does | Default | | --- | --- | --- | | **Framework** | Which framework the app uses, for defaults and the label on the project. | Detected | | **Node.js version** | The Node.js version for the build and the app. | 22 | | **Root directory** | The app's folder in the repository. Commands run there, and the output directory is relative to it. | `./` | | **Install command** | Installs dependencies. | From the lock file | | **Build command** | Builds the app. | Your `build` script | | **Output directory** | For a static site, the folder of files to serve. | Per framework | | **Skip a build when** | The ignored build step, below. | None | An empty field means "use the detected default". Through the API, sending `null` for a build field goes back to the default. The settings card shows who changed a setting last, and when. ### Root directory Set it to the folder that holds the app's `package.json`, such as `apps/web`. In a monorepo, the lock file and the `packageManager` field are still found at the repository root, so a pnpm or Yarn workspace installs as it should. The output directory must stay inside the root directory. If Orbits finds nothing to deploy (no `package.json`, and no `index.html` to serve as it is), the build fails with "Nothing to deploy". Point the root directory at the app's folder. ### Output directory Only static sites use it: it's the folder the build writes the site to, like `dist` or `build`. If the build finishes without creating it, the deployment fails at Uploading with "No dist directory to serve". If the folder has no `index.html`, the build log says so and the home page answers 404. Server apps don't use an output directory: they're run with their start command (see [server apps](https://docs.orbits.africa/deploy/frameworks#server-apps)). ## Ignored build step **Skip a build when** is a shell command Orbits runs after cloning, in the repository, before installing anything. If it exits with `0`, the build is skipped: the deployment ends **canceled**, saying why, and nothing changes in production. Any other exit code builds as usual. It's most useful in a monorepo, where every push builds every app made from the repository. To build an app only when its own folder changed: ```console $ git diff --quiet HEAD^ HEAD -- ./apps/storefront ``` `git diff --quiet` exits `0` when nothing changed, so the build is skipped. What the command gets: - the repository, cloned two commits deep, so `HEAD^` is the previous commit; - `git` and the Node.js image the build uses; - `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` (the branch) and `ORBITS_ENV` (`production` or `preview`), and the same values as `VERCEL_GIT_COMMIT_SHA`, `VERCEL_GIT_COMMIT_REF` and `VERCEL_ENV`, so scripts written for Vercel work as they are. It has **two minutes**. A command that runs longer is stopped and the commit builds. The project's own environment variables aren't given to it yet. ## Build cache Orbits keeps each project's package manager cache (npm, pnpm, Yarn or Bun) between builds, so installs after the first are faster. It's keyed by your lock file. If the cache can't be read, the build carries on without it. The framework's own build cache, such as Next.js's `.next/cache`, isn't carried between builds. To build without the cache, redeploy with **Clean build** instead of **Use the build cache**. That helps when a cached package is out of date or a build behaves differently from a clean checkout. ## Environment variables at build time The build gets the project's variables for its environment (Production for production deployments, Preview for previews). Frameworks bake variables meant for the browser into the build (`NEXT_PUBLIC_*`, `VITE_*` and the like), so changing one of those needs a redeploy to take effect. Orbits also sets: | Variable | Value | | --- | --- | | `CI` | `1` | | `SITE_URL` | The address the build is for: the project's production address for production, the deployment's own address for a preview. A variable you set yourself wins. | | `ORBITS_FLAGS`, `ORBITS_WORKFLOWS`, `ORBITS_API_URL` | Keys for [flags](https://docs.orbits.africa/features/flags) and [workflows](https://docs.orbits.africa/features/workflows), and the API address. A variable you set yourself wins. | A variable whose value contains a line break is skipped, with a line in the build log; multi-line values (such as a PEM key) aren't supported yet. See [environment variables](https://docs.orbits.africa/deploy/environment-variables). ## Deployment warnings A deployment can build fine and still be missing something. Orbits checks two things and shows what it finds as **warnings** on the deployment's page. Neither fails the build. ### Variables the code uses but the build didn't have Before building, Orbits scans your source (not `node_modules` or build output) for the public variables frontends bake in: - `import.meta.env.VITE_*` - `process.env.NEXT_PUBLIC_*` - `REACT_APP_*` - `PUBLIC_*` Any it finds that weren't set for the deployment's environment, nor in a committed `.env` or `.env.production`, are listed under **Missing variables**: > VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them. Your code may have a fallback, which is why it's a warning. To fix it, add the variables for that environment and redeploy. ### A page that broke as it loaded A few seconds after a deployment is ready, Orbits opens its home page in a browser to take the screenshot. If the page threw uncaught errors as it loaded (the first three are shown), or its first screen came out blank, the deployment says so: "The page threw an error" or "The page came out blank". A blank page with a missing-variable warning beside it usually means the app needs those variables to start. A later screenshot replaces this check. ## Through the API Build settings are the `build` object on a project, and the Node.js version is `node_version`. See [the projects API](https://docs.orbits.africa/api/projects). --- # Deployments Source: https://docs.orbits.africa/deploy/deployments What starts a deployment, its states and build steps, build logs, deployment addresses, and how to promote, roll back, redeploy and cancel. A deployment is one build of one commit. It never changes after it's built: a new push, a new variable or a new setting makes a new deployment. Changing what production serves only moves a pointer from one deployment to another. You find them on a project's **Deployments** page, and across every project on the team's **Deployments** page. ## What starts a deployment | Trigger | When | | --- | --- | | `create` | You create a project from a repository: its first production deployment starts at once. | | `git` | A push. The production branch builds production, any other branch a preview (see [Git providers](https://docs.orbits.africa/deploy/git)). | | `manual` | You deploy by hand, with `orbits deploy`, or an [upload](https://docs.orbits.africa/getting-started/upload-a-folder) completes. | | `redeploy` | You redeploy an existing deployment. | | `promote` | You promote a preview to production. | To deploy a branch by hand from the CLI: ```console $ orbits deploy --prod # the production branch's newest commit $ orbits deploy --branch feature/checkout # a preview of another branch ``` Owners, admins and members can deploy, redeploy, promote, roll back and cancel. Viewers can read everything but change nothing. A project that runs as a `function` needs Pro to deploy, redeploy or promote. On Free, what is live keeps running, but new builds of it are refused, and a build started by a push fails with "Pro plan required". See [plans](https://docs.orbits.africa/billing/plans). ## States and steps | State | Meaning | | --- | --- | | `queued` | Waiting for a builder. Shown as building. | | `building` | Running its steps. | | `ready` | Built. A production deployment is now live; a preview has its address. | | `failed` | A step failed. Nothing it built went live. | | `canceled` | Canceled by someone, or skipped by the [ignored build step](https://docs.orbits.africa/deploy/build-settings#ignored-build-step). | Every build goes through the same six steps, each with its own time: **Queued**, **Cloning repository**, **Installing packages**, **Building**, **Uploading** and **Going live**. A step can also be skipped when there's nothing to do in it. When a build fails, the deployment page shows why, from the build's own output (for example "Type error in lib/cart.ts, line 42"), and which step stopped. **Jump to error** scrolls the log to the line. ## Build logs The deployment page shows the build log grouped under its steps, with errors in red. While a build runs, the log streams live: lines appear within a second of the build printing them. A build keeps at most 5,000 log lines. From the terminal: ```console $ orbits logs dpl_… # a deployment's build log $ orbits logs dpl_… -f # follow it as it builds ``` Through the API, read the lines in pages, or follow them as server-sent events, which also tell you when steps change and when the build has ended. See [the deployments API](https://docs.orbits.africa/api/deployments). Build logs are about building. For what your app prints and the requests it serves, see [runtime logs](https://docs.orbits.africa/observe/runtime-logs). ## Preview and production Each deployment is either: - **Production**, built from the production branch (or promoted). The one production serves is marked **current**. Production keeps serving the current deployment until a new one is ready, so visitors never see a half-built site. - **Preview**, built from another branch, with its own address. See [previews](https://docs.orbits.africa/deploy/previews). The **Production only** filter on the Deployments page shows the deployments that have served production at some point (`went_live` in the API). The other filters are search (commit message, branch, sha or author), environment, status and branch. ## Deployment addresses Every deployment has its own address once its commit is known: ```text https://-.theorbits.app ``` For example `https://storefront-a1f9c2e.theorbits.app`. It answers while the deployment is production, or the newest ready preview of its branch. The project's own addresses (`.theorbits.app` and its custom domains) always serve the current production deployment. ## Screenshots and link previews A few seconds after a deployment is ready, Orbits loads its home page and takes a screenshot of the first screen (1280 by 800). It's on the deployment page, the inspector and the project card. Failed and canceled deployments, and workers, don't get one. The deployment page's **Open Graph** section shows how a link to the deployment looks when it's shared on X, LinkedIn, Facebook or Slack, from the tags on its home page, and warns when, for example, the image is a relative URL some link bots can't resolve. The same browser visit checks the page for errors and a blank first screen; see [deployment warnings](https://docs.orbits.africa/deploy/build-settings#deployment-warnings). ## Promote **Promote** takes a ready preview to production. Orbits rebuilds its commit with **production's** environment variables, as a new production deployment, and that goes live when it's ready. The current version stays live until then. Promoting a commit that is already live, or a deployment that isn't ready, is refused. Promoting also turns auto-deploy back on after a rollback. ## Roll back **Roll back** points production at an earlier production build straight away. Nothing is rebuilt, so it takes moments. You can roll back to any of the last three builds that served production. After a rollback, **auto-deploy pauses**, so the next push to the production branch doesn't replace the build you went back to. Pushes still build; they just don't go live. The toast's **Undo** puts back what production served before. To turn auto-deploy back on, choose **Turn it back on** from the project's overview (or promote a deployment). ```console $ orbits deployments rollback ``` :::note A rolled-back deployment runs with the project's current environment variables, not the ones it had when it was built, if it has to be started again. ::: ## Redeploy **Redeploy** builds the same commit again, in the same environment, as a new deployment. A production redeploy takes over when it's ready; production keeps serving the current build until then. Choose: - **Use the build cache**: faster, reuses packages from the last build. - **Clean build**: slower, starts from scratch. Useful when the cache is out of date. Redeploy after changing environment variables or build settings, so production picks them up. A deployment that failed before its commit was known rebuilds its branch's newest commit. For an upload project, the archive must still be one of the last five uploads. ```console $ orbits deployments redeploy ``` ## Cancel **Cancel deployment** stops a queued or building deployment. A queued one is canceled at once; a building one stops within a few seconds. Nothing it built goes live. A finished deployment can't be canceled. ## Commit statuses For projects from Git, each deployment sets a status on its commit, `Orbits – `, linked to the deployment's page: pending, then passed or failed. See [commit statuses](https://docs.orbits.africa/deploy/git#commit-statuses). ## Notifications A failed deployment shows in the bell and, depending on your team's settings, in email and Slack. So can a production deployment going live. See [notifications](https://docs.orbits.africa/team/notifications). ## Through the API Listing, creating, redeploying, promoting, rolling back and cancelling deployments, and reading their logs and screenshots, are in [the deployments API](https://docs.orbits.africa/api/deployments). --- # Preview deployments Source: https://docs.orbits.africa/deploy/previews Every branch you push gets a preview with its own address. Branch addresses follow a branch's newest preview, and you choose who can open previews. A **preview** is a deployment of any branch other than the production branch. It lets you, your team and your reviewers try a change on a real address before it reaches production. Production is never affected by a preview. ## How previews are made When **Preview pull requests** is on in the project's settings (it is by default), every push to a branch other than the production branch builds a preview of that commit. Previews use the project's **Preview** environment variables. If the branch has an open pull request (a merge request on GitLab), the preview carries its number, so you can find it from the pull request. On GitHub, GitLab and Bitbucket, the commit shows the `Orbits – ` status, which reads "Preview ready" when the preview is up and links to its deployment page. See [commit statuses](https://docs.orbits.africa/deploy/git#commit-statuses). You can also build a preview of any branch by hand: ```console $ orbits deploy --branch feature/checkout ``` Previews are built from branches pushed to the repository itself. Pull requests from forks are ignored unless **Build pull requests from forks** is on in the integration's settings. ## Preview addresses Each preview has two addresses. | Address | Example | Serves | | --- | --- | --- | | The deployment's own | `storefront-a1f9c2e.theorbits.app` | That one commit, while it's the branch's newest ready preview | | The branch address | `storefront-git-feat-apple-pay.theorbits.app` | Whatever the branch's newest ready preview is, so it stays the same as you push | The branch address is `-git-.theorbits.app`, with the branch name made safe for an address (a long one is shortened and given a short hash). Use the address Orbits shows rather than building it yourself. The project's **Domains** page lists the branch addresses under **Follows the branch**. To serve a branch on a domain of your own, such as `staging.example.com`, add the domain and choose **Serve a preview branch**. See [custom domains](https://docs.orbits.africa/domains/custom-domains). ## How long previews are served Orbits serves the newest ready preview of each branch. An older preview of the same branch stops answering once a newer one is ready. A preview that hasn't been replaced for a while (14 days) stops being served too, and its address stops answering. Push to the branch again, or redeploy the preview, to bring it back. On Pro, at most **three** previews of a project are served at once, the most recently built ones; when a fourth is ready, the oldest stops. Production isn't counted and is never stopped. A preview that stops can be redeployed. ## Promote a preview When a preview looks right, **Promote** it: Orbits rebuilds its commit with production's variables and makes that production when it's ready. See [promote](https://docs.orbits.africa/deploy/deployments#promote). ## Who can open previews Production is always public. Previews are protected by the project's **Deployment protection** setting, **Who can open preview links**: | Choice | Who gets in | | --- | --- | | **Anyone with the link** | Anyone. | | **Team members only** | Members of the project's team, after signing in to Orbits. The default for new projects. | | **Password** | Anyone with the preview password. | Protection is checked on every request to a preview, at its deployment address and its branch address. ### Password Choose **Password**, then set the **Password for previews** (at least 8 characters). A visitor to a preview sees a password page; the right password is remembered in that browser for 12 hours. Changing the password asks everyone for it again. Use **Change the password** to set a new one; Orbits never shows the current one. ### Team members only A visitor who isn't signed in is sent to Orbits to sign in. A member of the team then gets straight in, and the browser is remembered for 12 hours. Someone not in the team is told they don't have access. :::warning[Team-only previews are not enforced yet] The sign-in step for **Team members only** isn't switched on yet, so previews set to it currently open for anyone with the link. If a preview must stay private now, use **Password**. ::: Changing deployment protection is for owners and admins. ## Turning previews off Turn off **Preview pull requests** under Git in the project's settings, and pushes to other branches stop building. Turning off **Deploy every push** stops all builds from pushes, production included. Disconnecting the Git provider also stops previews; existing deployments keep working. See [disconnecting](https://docs.orbits.africa/deploy/git#disconnect-a-provider). --- # Environment variables Source: https://docs.orbits.africa/deploy/environment-variables Set keys and secrets per environment, mark them sensitive, reveal, import a .env file, delete with undo, pull them for local development, and redeploy to apply a change. Environment variables hold your app's configuration and secrets: API keys, database URLs, feature switches. They are available when the project builds and while it runs, and values are encrypted. Open a project's **Environment variables** page. Each row is one key, with the environments it applies to. ## Environments A variable applies to any mix of three environments: | Environment | Used by | | --- | --- | | **Production** | Production deployments, including promoted ones. | | **Preview** | Preview deployments of other branches. | | **Development** | Your own machine, through `orbits env pull`. | New variables apply to Production and Preview unless you pick otherwise. A key has one value, shared by every environment it applies to. ## Add a variable Press **Add a variable**, give the **Key** and the value, tick the environments, and save. Keys use letters, digits and underscores and don't start with a digit, such as `STRIPE_SECRET_KEY`. ```console $ orbits env add STRIPE_SECRET_KEY ``` The CLI reads the value from standard input when it isn't on the command line, hidden at a terminal. In a script: `printf %s "$VALUE" | orbits env add STRIPE_SECRET_KEY`. A key that already exists can't be added again; edit it instead. ## Sensitive variables **Sensitive** is ticked by default. A sensitive value is write-only: "Nobody can read it back, only replace it." Not you, not an owner, not the API. The page shows no eye icon, **Reveal value** or copy for it, and `orbits env pull` leaves it out. You can only edit it by typing a new value. Untick **Sensitive** for values you need to read back. With the CLI, variables are sensitive by default too; `--plain` makes one readable. Whether a variable is sensitive is set when you add it and can't be changed afterwards. To change it, delete the variable and add it again. ## Reveal a value For a variable that isn't sensitive, **Reveal value** (or the eye icon) shows it, and the menu copies it. Every reveal is recorded in the team's [activity](https://docs.orbits.africa/team/activity) with who did it and which key, never the value. The list shows a value in clear without revealing only when the variable isn't sensitive and its key is meant for the browser anyway: it starts with `NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`, `REACT_APP_` or `EXPO_PUBLIC_`, or ends with `_PUBLIC_KEY`. Everything else shows dots until revealed. ```console $ orbits env ls # keys and environments $ orbits env ls --show-values # with readable values ``` ## Edit a variable Choose **Edit** from the row's menu. The key is read-only ("To rename a key, add a new one and delete this one."). Type a new value, or leave the value empty to keep the current one and change only the environments. The new value is used from the next deployment. ## Import a .env file Press **Import .env** and drop a `.env` file or paste its contents. Each line becomes a variable, applied to the environments you pick. Keys that already exist are replaced, value and environments, in the environments you pick, and the dialog warns you which ones before you import. The Configure step of a new project has **Import .env** too, so you can bring your variables in before the first deploy. ## Delete and undo Choose **Delete** from the row's menu and type the key to confirm. The variable disappears at once, and the toast offers **Undo** for **10 minutes**: ```console $ orbits env rm STRIPE_SECRET_KEY $ orbits env restore STRIPE_SECRET_KEY # within 10 minutes ``` Restoring brings back the value and environments it had, unless a variable with that key has been added since. Deployments made after the delete don't get the variable. ## Redeploy to apply a change Variables are read when a deployment is built. Changing one doesn't touch deployments that are already running: they keep the values they were built with. After a change, the page shows a banner such as "You changed 1 variable. Redeploy so production picks it up.", with **Redeploy to apply**, and marks the changed rows **New**. Redeploy production to pick the change up. Variables a framework bakes into the browser bundle (`NEXT_PUBLIC_*`, `VITE_*` and so on) always need a rebuild to change. See [redeploy](https://docs.orbits.africa/deploy/deployments#redeploy). ## Pull variables for local development `orbits env pull` writes an environment's readable variables to a file for local development: ```console $ orbits link $ orbits env pull .env.local ``` It pulls Development by default and writes the file with mode `0600`. Sensitive variables can't be read back, so they're left out, and the CLI names them so you know what's missing. It warns you if Git doesn't ignore the file. Keep `.env.local` out of Git; Next.js projects ignore it already. Every pull is recorded in the team's activity. ## What every deployment also gets Orbits adds a few variables to every deployment, unless you set a variable with the same name yourself: | Variable | What it is | | --- | --- | | `SITE_URL` | The address the deployment is for: production's address for production, the deployment's own address for a preview. | | `ORBITS_FLAGS` | The key [`@useorbits/flags`](https://docs.orbits.africa/features/flags) reads the environment's flags with. | | `ORBITS_WORKFLOWS` | The key [`@useorbits/workflows`](https://docs.orbits.africa/features/workflows) uses. | | `ORBITS_API_URL` | The Orbits API's address. | Server apps also run with `NODE_ENV=production` and `PORT`, which your server should listen on. Builds run with `CI=1`. ## Limits | | Limit | | --- | --- | | Variables per project | 1,000 | | Variables in one import | 500 | | Size of one value | 32 KiB | | Line breaks in a value | Not supported yet: such a variable is skipped, with a line in the build log | ## Who can do what Owners, admins and members add, edit, delete, reveal and pull variables. Viewers see the keys and environments, never values. API tokens follow the same rules as the person who made them, with one more: a **read** token never reads a value. Reveal and pull are writes in the API, so they need a **full** token. See [API tokens](https://docs.orbits.africa/team/api-tokens). The API is in [environment variables](https://docs.orbits.africa/api/environment-variables). --- # Project settings Source: https://docs.orbits.africa/deploy/projects Rename a project, pause and resume it, move it to another team, delete it, and what its workload and region mean. A project's **Settings** page has its General, Build, Git, Deployment protection and Advanced settings. Settings save as you change them; the page says "All changes saved". Owners and admins change settings; "Viewers can look but not change settings", and neither can members. Changes to how a project builds apply from the next deployment. See [build settings](https://docs.orbits.africa/deploy/build-settings) for the Build section and [Git providers](https://docs.orbits.africa/deploy/git#deploy-on-push) for the Git section. ## Rename a project Change **Project name** under General. The project's **slug** is its name in lower case with hyphens, and the slug is its free address, so renaming changes the address too: `storefront.theorbits.app` becomes `shop.theorbits.app`. Deployment and branch addresses change with it. Update anything that links to the old address. The slug must be unique across all of Orbits: if another project has it, the rename is refused and you pick another name. A slug is 3 to 40 characters of lower-case letters, digits and hyphens, starting and ending with a letter or digit; a few reserved words can't be used. Custom domains aren't affected by a rename. ## Pause and resume Under **Advanced**, **Pause** the project with the **Paused** toggle: "Visitors see a paused page and nothing deploys until you turn it back on. Domains and data stay." While a project is paused: - its production address, previews and custom domains answer **503** with Orbits' paused page; - its apps stop; - nothing deploys, from pushes or by hand. Its domains, variables, deployments and the builds production can come back to are all kept. Turn **Paused** off and production is served again within moments. ```console $ orbits projects pause # the folder's linked project $ orbits projects resume ``` ## Transfer to another team Under **Advanced**, **Transfer** moves the project to another team. Pick the team under **Move to**. You need to be an owner or admin of the project's team, and an **owner** of the team it moves to ("You need to be an owner there"). If you don't own another team, there's nowhere to move it. The project keeps its name, slug and free address. Its deployments, environment variables and alerts go with it. Members of the old team who aren't in the new one lose access to it. Things to check after a transfer: - **Git.** Pushes reach a project through its team's Git connection. Connect the same provider, with access to the repository, in the new team. - **Custom domains.** Domains belong to a team. Check the project's Domains page in the new team, and add any domain it should serve there. API tokens can't transfer projects; it needs a signed-in person. ## Delete a project Under **Advanced**, **Delete project** "Deletes every deployment, variable and log. Domains are detached, not deleted. This can't be undone." The dialog counts what goes: deployments and their build logs, environment variables, flags and their history, and the domains that will be detached. Type the project's name to confirm. Its custom domains stay in the team's **Domains and DNS**, shown as not in use, ready to point at another project. ```console $ orbits projects delete storefront ``` Deleting is for owners and admins. It runs as an [operation](https://docs.orbits.africa/getting-started/concepts#operations). ## Workload The workload is how the project runs: `static`, `function`, `app`, `worker` or `container`. It's set when the project is created, from the framework unless you choose one, and **can't be changed afterwards**. To run the same repository another way, create a new project from it. See [workloads](https://docs.orbits.africa/deploy/frameworks#workloads). On Free, server frameworks run as `app`; the `function` workload is part of Pro. The **Functions** section's **Time limit** and **Memory** aren't applied yet. ## Region Every project runs in Abuja (`abj-1`), the only region. The **Region** field shows it and has nothing else to choose. See [region](https://docs.orbits.africa/getting-started/region). ## Notifications A project uses its team's notification settings. **Team notification settings** on the project's Settings page leads there. See [notifications](https://docs.orbits.africa/team/notifications). ## Through the API Getting and changing a project, pausing, transferring and deleting it are in [the projects API](https://docs.orbits.africa/api/projects). --- # Domains Source: https://docs.orbits.africa/domains/overview Every project's free theorbits.app address, the custom domains your team adds, what a domain can serve, and where to manage them. Every project answers on a free address the moment it's deployed. You can add domains you own on top, point them at a project's production or at a branch, or make them redirect. ## The free address Each project gets `https://.theorbits.app`, from its slug, with a certificate. It always serves the project's current production deployment. On the project's **Domains** page it's listed as **Free address from Orbits**. The slug is unique across Orbits, so the free address is yours for as long as the project keeps its name. Renaming the project changes it (see [rename a project](https://docs.orbits.africa/deploy/projects#rename-a-project)). Orbits also gives each deployment and each branch with a ready preview an address under `theorbits.app`: | Address | Serves | | --- | --- | | `.theorbits.app` | Production | | `-.theorbits.app` | One deployment | | `-git-.theorbits.app` | A branch's newest ready preview | See [deployment addresses](https://docs.orbits.africa/deploy/deployments#deployment-addresses) and [preview addresses](https://docs.orbits.africa/deploy/previews#preview-addresses). ## Custom domains A custom domain is a name you own, such as `shop.example.com` or `example.com`, added to your **team**. Domains belong to the team rather than to one project, so: - the team's **Domains and DNS** page lists every domain the team has, with filters for status, DNS and project; - a project's **Domains** page lists the domains pointing at that project ("Addresses that point at this project. Their DNS records live in the team's Domains and DNS."); - a domain can be added before any project uses it, and moved from one project to another; - deleting a project detaches its domains rather than deleting them. A domain belongs to one team. If another team already has it, adding it is refused. ## What a domain can serve When you add a domain, or later with **Change** on its hostname card, you choose what it does: | Choice | What visitors get | | --- | --- | | **Serve production** | The project's current production deployment. | | **Serve a preview branch** | The newest ready preview of the branch you pick, as it changes with each push. Good for `staging.example.com`. | | **Redirect to another domain** | A 308 redirect, keeping the path, to another of the team's domains or the project's free address. Good for sending `www.example.com` to `example.com`. | | **No project** | Nothing yet: the domain is kept, shown as **Not in use**. | The project's Domains page shows production's domains, the branch addresses under **Follows the branch**, and redirects under **Redirects**. ## Two ways to set up DNS | | **Add one record** | **Use Orbits DNS** | | --- | --- | --- | | Your DNS stays | At your current provider | Moves to Orbits | | What you do | Add one record where the domain's DNS is hosted | Point the domain's nameservers at `ns1.theorbits.app` and `ns2.theorbits.app` | | Good for | One subdomain, or keeping a DNS setup you already have | A whole domain, managing every record here, including email | Either way, Orbits checks the DNS, issues the certificate once it's found, then serves the domain. See [custom domains](https://docs.orbits.africa/domains/custom-domains) for adding one, and [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) for handing your DNS to Orbits. ## States | State | Meaning | | --- | --- | | **Waiting for DNS** (`pending`) | The record (or nameservers) isn't there yet. | | **Valid** | DNS points at Orbits. | | **Misconfigured** | A record is there but points elsewhere; the domain page shows what was found. | Separately, each domain's certificate is waiting, active or failed. The team page's stat cards count the domains that need attention. ## Who can manage domains Owners, admins and members add, change and remove domains and DNS records. Viewers see them. Anyone in the team can press **Check now**. ## Next ::::cards :::card[Add a custom domain]{href=/domains/custom-domains} The record to add, verification, certificates and what to do when it's misconfigured. ::: :::card[Use Orbits DNS]{href=/domains/orbits-dns} Move your nameservers to Orbits and manage records and zone files here. ::: :::card[Set up email]{href=/domains/email-records} Add the MX and SPF records for Google Workspace, Microsoft 365 or Zoho in one step. ::: :::: --- # Add a custom domain Source: https://docs.orbits.africa/domains/custom-domains Point a domain you own at a project with one DNS record or with Orbits DNS. Orbits verifies it, issues and renews its certificate, and tells you when something needs attention. You can add a domain from a project's **Domains** page or from the team's **Domains and DNS** page. From the project, it's linked to that project at once; from the team page, choosing a project is optional. ## 1. Add the domain Press **Add domain** and type the address you want visitors to use, such as `shop.example.com`. Orbits tidies what you type: a scheme, a path or a trailing dot comes off, and it's lower-cased. Then choose what it serves (production, a preview branch, or a redirect; see [what a domain can serve](https://docs.orbits.africa/domains/overview#what-a-domain-can-serve)) and how its DNS is set up: - **Add one record**: keep your DNS provider and add a single record there. - **Use Orbits DNS**: hand the domain's DNS to Orbits. See [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns). As you type, the dialog's note says what adding the name will do before anything is saved: the record it needs, the Orbits DNS zone it falls in if your team has one, or the nameservers to set. A name inside a zone your team already runs on Orbits DNS is on Orbits DNS too, and Orbits creates its record for you: there's nothing to add. If your team already has the domain and it serves nothing yet, adding it from a project links it to that project. ## 2. Add the record With **Add one record**, the next step shows the one record to add at your DNS provider. | Domain | Record | Name | Value | | --- | --- | --- | --- | | A subdomain, such as `shop.example.com` | **CNAME** | `shop` | `cname.theorbits.app` | | An apex, such as `example.com` | **A** | `@` | The address the domain's page shows | A CNAME can't sit at an apex, so an apex gets an A record. Copy the value from the domain's page rather than from these docs. A subdomain also counts as pointing here if your provider flattens the CNAME into A records with Orbits' address alone. :::warning[Remove other records at the same name] Orbits has no IPv6 address. An AAAA record at the name, or A records that point anywhere else as well, make the domain **misconfigured**. Delete them at your provider. ::: There's no TXT record to add: DNS pointing at Orbits is the proof that the domain is yours. ## 3. Verification Orbits looks for the record: - as soon as you add the domain; - every minute while it waits (every 15 minutes once it has waited a day); - every 10 minutes once it's valid, so a record that changes later is noticed; - at once when anyone presses **Check now** (a domain checked in the last 10 seconds isn't looked up again). Orbits asks your domain's own nameservers, so a record you just added is seen straight away rather than after a cached "no such name" expires. Your visitors' own resolvers may still need a little time. The domain page shows the state, the record it needs and what the last check found, with **Last checked**: | State | What to do | | --- | --- | | **Waiting for DNS** | Nothing was found yet. Add the record, then press **Check now**. | | **Valid** | Done: the certificate follows. | | **Misconfigured** | Something is there, but it points elsewhere ("We found CNAME old-host.example.net where Orbits expects cname.theorbits.app"). Change the record at your provider. | A failed lookup on Orbits' side changes nothing: a valid domain stays valid. ## 4. The certificate Orbits issues a certificate for each hostname on its own, from Let's Encrypt (an HTTP-01 challenge), once the domain points here and serves a project. You don't upload anything. | Certificate | Meaning | | --- | --- | | **Nothing to secure yet** | The domain isn't pointing here, or isn't in use. | | **Waiting for DNS** | DNS points here and the certificate is being issued. Orbits waits until public DNS answers for the name before asking for it, which can take a few minutes for a new domain. | | **Active** | Issued, with its dates. The domain is now served. | | **Failed** | The last try failed. Orbits tries again 5, 15, 30 and then 60 minutes after each failure. | The domain only starts serving once its certificate is there. A certificate renews by itself about 30 days before it expires. A certificate can fail when the domain stops pointing here before it is issued. If your domain has CAA records, they must allow Let's Encrypt. ## Emails about your domain - **DNS needed**: an hour after you add a domain, if its record still isn't there, the person who added it gets one email with the record to add. - **Domain live**: when its certificate arrives, the person who added it gets one email. - **A domain or certificate needs attention**: when a domain's DNS moves away from Orbits (misconfigured), when a certificate can't be issued, or when one is within 14 days of expiring and hasn't renewed. This goes to everyone who can deploy, and to Slack, Microsoft Teams and webhooks, when the team's notification switch for it is on. See [notifications](https://docs.orbits.africa/team/notifications). Turning the team's domain notification switch off stops all of them. ## Change what a domain serves On the domain's page, the hostname card shows what it serves. **Change** points it at another project, a branch, production again, a redirect, or nothing. The name and its DNS mode can't change: remove the domain and add it again. ## Remove a domain **Remove domain** on the domain's page, after the confirmation. The project stops answering on it within a minute and its certificate is deleted. The record at your DNS provider stays until you delete it there. ## Troubleshooting **It stays Waiting for DNS.** Check the record's name and value exactly, at the provider that actually hosts the domain's DNS (the one its nameservers point to). Some providers want the name without the domain (`shop`), others the full name. Then press **Check now**. **It's Misconfigured.** Look at what the domain page says it found. An old CNAME, an AAAA record, or an A record to another host are the usual causes. **The certificate failed.** Make sure the domain still points here and nothing else at the name answers. Orbits retries on its own. The API for domains is in [domains](https://docs.orbits.africa/api/domains). --- # Use Orbits DNS Source: https://docs.orbits.africa/domains/orbits-dns Hand a domain's DNS to Orbits by pointing its nameservers at ns1 and ns2.theorbits.app, then manage its records, import a zone file and set up email here. With Orbits DNS, Orbits answers for the whole domain. It keeps the records your projects need by itself, and you manage every other record (email, verification TXT records and so on) on the domain's page in Orbits. ## Hand a domain to Orbits Press **Add domain** on the team's **Domains and DNS** page, type the domain and choose **Use Orbits DNS** ("Hand its DNS to Orbits and manage every record here."). The domain becomes a **zone**, and its page shows the nameservers to use: ```text ns1.theorbits.app ns2.theorbits.app ``` What you do with them depends on the domain: ::::tabs :::tab[An apex, like example.com] At your **registrar** (where you bought the domain), replace its nameservers with `ns1.theorbits.app` and `ns2.theorbits.app`. Remove any others. ::: :::tab[A subdomain, like dev.example.com] A subdomain can be a zone of its own while the rest of the domain stays where it is. At the DNS provider of the parent domain, add two **NS** records for the subdomain: `dev` → `ns1.theorbits.app` and `dev` → `ns2.theorbits.app`. ::: :::: Before you switch, copy your existing records into Orbits (see [import a zone file](#import-a-zone-file)), so email and anything else on the domain keeps working the moment the nameservers change. ## Verification The domain page's **Nameservers** card shows what Orbits found. The zone is **valid** once all of its nameservers are Orbits', and **misconfigured** while only some are. Orbits asks the parent zone (for `example.com`, the `.com` registry) which nameservers it hands out, so the change shows as soon as the registry publishes it rather than after a cached answer expires. Registries can still take a few hours to publish: "Nameserver changes can take a few hours to spread." If the nameservers still aren't Orbits' an hour after you added the zone, the person who added it gets one email saying what to change and what was found. ## Records Orbits keeps You don't add records for your projects: Orbits creates them, marked **Managed by Orbits**, and keeps them in step with the team's domains. - When the zone's own name serves a project, it gets an **A** record to Orbits and, for an apex, a `www` **CNAME** to `cname.theorbits.app` beside it. Add your own `www` record and it replaces Orbits'. - Each name in the zone that serves a project, such as `shop.example.com`, gets a **CNAME** to `cname.theorbits.app`. Managed records can't be edited or deleted on the zone's page: "Records used by a project are created by Orbits. Change them from that project's Domains page." To serve another name, add it as a domain from the project; Orbits adds its record, so there's nothing to wait for at another provider. When a name in the zone starts serving a project, your own A, AAAA or CNAME records at that name are deleted, since you've chosen to point it at the project. Domains added inside the zone are on Orbits DNS whatever you choose, and removing the zone hands its subdomains back to outside DNS. ## Your records The zone's page lists its records. Press **Add record** to add one, or use a record's menu to edit or delete it. Changes on Orbits DNS go live in under a minute. | Type | Value | | --- | --- | | **A** | An IPv4 address | | **AAAA** | An IPv6 address | | **CNAME** | A hostname | | **MX** | A priority and a mail server, such as `10 mx.example.com` | | **TXT** | The text to publish, without quotes | | **CAA** | Flags, a tag and a value, such as `0 issue "letsencrypt.org"` | Names are relative to the zone, with `@` for the zone itself, and can include `*.` for a wildcard and underscores (for `_dmarc` and similar). Values are up to 2,048 characters. **TTL** is one of Auto (5 minutes), 1 minute, 5 minutes, 1 hour or 1 day. Rules a record must follow: - A CNAME can't sit at `@`: use an A record there. - A CNAME can't share its name with any other record. - A name Orbits manages for a project can't take another record there. - The same record (type, name and value) can't be added twice. The zone's SOA and NS records are Orbits' and aren't listed. ## Import a zone file To bring records over from another provider, export the zone from it (most offer a BIND zone file) and choose **Import zone file** on the zone's page. Paste the file or drop it in. Orbits shows what it found before anything is saved, such as "4 records found: 1 new, 3 already here", then **Import** adds the new ones. - Records already in the zone (same type, name and value) are left as they are. - Lines Orbits can't use are counted as skipped, not guessed at: SOA and NS records, records for another domain, types Orbits doesn't host, and names it manages for a project. - A record written over several lines in parentheses, such as a long DKIM key, counts as one. - A TTL is rounded to the nearest one Orbits offers. A zone file can be up to 200,000 characters. ## Email **Email setup** on the zone's page adds the MX and SPF records for Google Workspace, Microsoft 365 or Zoho Mail in one step. See [email records](https://docs.orbits.africa/domains/email-records). ## Limits and what's not available yet - **Zones don't nest.** A zone around one your team already has on Orbits DNS is refused, and so is one inside or around another team's zone. - **One team per name.** A domain or zone belongs to one team. - Not available yet: DNSSEC, and zone transfers to a secondary nameserver. The API for records and zone imports is in [DNS](https://docs.orbits.africa/api/dns). --- # Email records Source: https://docs.orbits.africa/domains/email-records On a domain that uses Orbits DNS, Email setup adds the MX and SPF records for Google Workspace, Microsoft 365 or Zoho Mail in one step. Hosting a site on Orbits doesn't include a mailbox, but if your domain uses [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns), Orbits can add the DNS records your email provider needs. You get mail from your provider as before; Orbits only publishes the records that send it there. Email setup is for zones on Orbits DNS. If your domain's DNS is at another provider, add your email provider's records there. ## Set up email On the zone's page in **Domains and DNS**, press **Email setup** and pick your provider: - **Google** (Google Workspace) - **Microsoft** (Microsoft 365) - **Zoho** (Zoho Mail) - **Something else**: adds nothing, for you to add the records yourself. The dialog shows how many mail records the zone has now ("Already set up · 5 records"), which provider is **Active**, and what each provider would add. Press **Add records** to apply. Choosing a provider replaces the mail records of the one before: MX records, the SPF TXT record and Microsoft's `autodiscover` CNAME. Your DMARC record and other TXT records stay. Choosing **Something else** clears the provider and keeps every record, for you to manage. ## The records added All with a TTL of one hour, at the zone's own name (`@`) unless noted. ::::tabs :::tab[Google] | Type | Name | Value | | --- | --- | --- | | MX | `@` | `1 aspmx.l.google.com` | | MX | `@` | `5 alt1.aspmx.l.google.com` | | MX | `@` | `5 alt2.aspmx.l.google.com` | | MX | `@` | `10 alt3.aspmx.l.google.com` | | MX | `@` | `10 alt4.aspmx.l.google.com` | | TXT | `@` | `v=spf1 include:_spf.google.com ~all` | ::: :::tab[Microsoft] | Type | Name | Value | | --- | --- | --- | | MX | `@` | `0 .mail.protection.outlook.com` (for `example.com`, `0 example-com.mail.protection.outlook.com`) | | TXT | `@` | `v=spf1 include:spf.protection.outlook.com -all` | | CNAME | `autodiscover` | `autodiscover.outlook.com` | ::: :::tab[Zoho] | Type | Name | Value | | --- | --- | --- | | MX | `@` | `10 mx.zoho.com` | | MX | `@` | `20 mx2.zoho.com` | | MX | `@` | `50 mx3.zoho.com` | | TXT | `@` | `v=spf1 include:zoho.com ~all` | ::: :::: A record that would clash with one of yours, or with a record Orbits manages for a project, isn't added; the dialog leaves it out of what it adds. If your provider gives your account different records from these, choose **Something else** and add the records it gives you with **Add record**. ## DKIM and DMARC Email setup doesn't add DKIM or DMARC. - **DKIM** keys are made by your email account, so only your provider can give them to you. Copy the DKIM record from its admin console and add it with **Add record**. - **DMARC** is a TXT record at `_dmarc` that you write for your own policy, for example `v=DMARC1; p=none; rua=mailto:dmarc@example.com`. Add it with **Add record**; Email setup never changes it. ## Editing the records Mail records that came with Email setup are marked as used by email on the zone's page and stay editable, like your own. Choosing a provider again in Email setup replaces the zone's MX, SPF and autodiscover records with that provider's. ## Through the API Reading the dialog's state and setting the provider are in [DNS](https://docs.orbits.africa/api/dns). --- # Runtime logs Source: https://docs.orbits.africa/observe/runtime-logs Every request your app was sent and every line it printed while running, kept for 7 days. Search and filter them on the project's Logs page, from the CLI or through the API. ## What the Logs page shows Open a project and choose **Logs**. The page lists two kinds of entry, newest first: - **Requests**: every request Orbits' edge sent to one of the project's deployments, production and previews alike. Each has its status, method, path and how long it took. - **Functions**: every line the project's deployments printed while running, on standard output or standard error. Each has its message and the stream it came from. Build output is not here. It belongs to a deployment, so it is on that deployment's page (see [build logs and runtime logs](#build-logs-and-runtime-logs) below). Requests and output lines are separate entries, and Orbits does not link them: an app's output is whatever it printed, whichever request it happened to be serving. To tie the two together, log the `X-Request-Id` header. The edge sends it with every request, and the same id is shown as the request's **Request ID** on the Logs page. :::note[Kept for 7 days] Runtime logs are kept for 7 days, the page's longest range, and are dropped a whole day at a time after that. If you need them for longer, copy them out with the [API](https://docs.orbits.africa/api/logs) or the CLI before they go. ::: ## Live and Paused The page starts **Live**: it checks for new entries every few seconds and adds them at the top. Choose **Paused** in the top corner to stop it moving while you read; choose **Live** again to carry on. ## Search and filters The toolbar above the list narrows what you see. Filters combine, and the URL keeps them, so you can share a filtered view with a teammate. | Control | What it does | | --- | --- | | **Search logs** | Matches a path or a message, in any case, or exactly a request ID, a status (`502`) or a method (`POST`). A request ID on its own (32 hex characters, as the edge makes them) finds just that request. Up to 200 characters. | | **Source** | **Requests** or **Functions**. **All** shows both. | | **Level** | **Info**, **Warning** or **Error**. | | **Status** | `2xx`, `3xx`, `4xx` or `5xx`. Requests only: output lines never match a status. | | **Time** | **Last hour** (the default), **Last 24 hours** or **Last 7 days**. | ### How levels are decided | Entry | Info | Warning | Error | | --- | --- | --- | --- | | A request | 1xx, 2xx and 3xx answers | 4xx answers | 5xx answers | | An output line | Anything else | The line mentions a warning | The line was written to standard error, or mentions an error | When nothing matches, the page says so and offers to widen the time range or clear the filters. The count above the list goes up to 10,000; beyond that it shows **10,000+**. Choose **Load more** at the foot of the list for older entries. ## One log entry Pick an entry and the panel beside the list shows all of it. For a **request**: the status and `METHOD /path`, the time, the duration, the region, the host it was sent to, the deployment that answered (linked to its page) and the request ID, then **Request headers**. For an **output line**: its level, the whole **Message**, the time, the stream (`stdout` or `stderr`), the region, the host and the deployment. A link to an entry keeps working while the entry exists. Once it is older than 7 days, it is gone. ### What is and isn't stored Logs are built to be safe to keep: - **Query strings are never stored.** A path is kept without its `?…`, because query strings often carry tokens. - **Client IP addresses are masked**, to the first two parts of an IPv4 address (`102.89.x.x`) or the first three groups of an IPv6 address. - **Only four request headers are kept**: `user-agent`, `accept`, `content-type` and `referer`, plus `x-forwarded-for`, masked. Cookies and `authorization` are never read. - **An output line** is kept without its colour codes, up to 8,192 characters. What your app prints is kept as it was printed, so don't print secrets. ## Build logs and runtime logs | | Build log | Runtime logs | | --- | --- | --- | | What it is | What the build printed, step by step: Queued, Cloning repository, Installing packages, Building, Uploading, Going live | Requests to the running app, and what it printed while running | | Where | The deployment's page, and live on the page while it builds | The project's **Logs** page | | Size | At most 5,000 lines per build | Everything, for 7 days | | Follow it live | Yes, while the build runs | Yes, with **Live** | A failed build is told in its build log, not here. See [deployments](https://docs.orbits.africa/deploy/deployments). ## From the CLI ```console $ orbits logs --runtime $ orbits logs --runtime -f --level error $ orbits logs --runtime --since 24h --source requests --search /checkout ``` `-f` follows new entries as they arrive. `--since` takes `1h`, `24h` or `7d`. `orbits logs ` (without `--runtime`) shows a build's log instead. See the [CLI](https://docs.orbits.africa/cli). ## From the API `GET /v1/teams/{team}/projects/{project}/logs` returns a page of entries with the same filters as the page: `q`, `source` (`requests` or `functions`), `level` (`info`, `warning`, `error`), `status` (`2xx` to `5xx`), `range` (`1h`, `24h`, `7d`; default `1h`) and `limit` (1 to 500, default 50). Send the answer's `next_cursor` back as `cursor` for the next page. ```console $ curl -s "https://api.theorbits.app/v1/teams/acme/projects/storefront/logs?level=error&range=24h" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` ```json title="One entry" { "id": "log_…", "at": "2026-11-10T09:14:03.218Z", "source": "requests", "level": "error", "status": 502, "method": "POST", "path": "/api/checkout", "duration_ms": 1840, "message": null, "stream": null, "request_id": "4f1c…", "host": "storefront.theorbits.app", "region": "abj-1", "deployment": { "id": "dpl_…" }, "headers": [["user-agent", "Mozilla/5.0 …"]] } ``` `GET .../logs/{log}` returns one entry by its `log_` id. Both answer `503` if logs can't be read for a moment: try again shortly. Any member of the team can read logs, including viewers and a read-only [API token](https://docs.orbits.africa/team/api-tokens). The full reference is at [API › Logs](https://docs.orbits.africa/api/logs). ## Related ::::cards :::card[Observability]{href=/observe/observability} Production's requests, errors and response times as charts. ::: :::card[Alerts]{href=/observe/alerts} Be told when errors or response times cross a line. ::: :::: --- # Observability Source: https://docs.orbits.africa/observe/observability Production's traffic at a glance. Requests, server errors and response times over time, the busiest routes, status codes and regions, worked out from your project's runtime logs. ## What it shows Open a project and choose **Observability**. The page charts how production is doing: the requests Orbits' edge sent to the project's production deployments, at the project's address or a build's own address. Previews are left out. Everything on it comes from the [runtime logs](https://docs.orbits.africa/observe/runtime-logs), so there is nothing to install. It is worked out each time you open the page. | Panel | What it tells you | | --- | --- | | **Requests** | Requests per bucket, with server errors (5xx) marked, and the total against the period before | | **Response time, p75 and p99** | How long the slower requests took, per bucket. The totals add p50 | | **By route** | The 20 busiest routes, each with its requests, errors, p75 and p99. **Most errors first** sorts them by errors | | **Status codes** | Requests by class: `2xx`, `3xx`, `4xx`, `5xx` | | **Regions** | Requests by region. Abuja (`abj-1`) is the only one with traffic | | **Alerts** | The project's alert rules and their state. See [alerts](https://docs.orbits.africa/observe/alerts) | Response times are milliseconds from the edge receiving a request to the last byte of the answer. Percentiles are exact, not estimates: p75 is the time three in four requests beat, p99 the time 99 in 100 beat. ## Time range and filters | Control | Choices | | --- | --- | | **Time range** | **1 hour**, **24 hours** (the default) or **7 days** | | **Route** | One of the 100 busiest routes in the range | | **Status** | `2xx`, `3xx`, `4xx` or `5xx`. Narrows every panel except **Status codes**, so you can still see the split | | **Region** | A region code | The charts are cut into buckets on Lagos time: | Range | Buckets | | --- | --- | | 1 hour | 12 of 5 minutes | | 24 hours | 24 of an hour | | 7 days | 7 of a day | The last bucket is the one still filling, so it usually looks lower than the rest. Buckets where nothing came in show zero. The totals compare the range with the same length of time before it ("on the hour before"). The project's overview page uses the same numbers over 6 hours, in 12 buckets of 30 minutes, for its health chart. ## How routes are grouped Routes are paths with the parts that vary taken out, so one page with many ids shows as one row: - A path segment that looks like an id becomes `[id]`: `/products/8412` is `/products/[id]`. - A static folder's files are one route: everything under `/_next/` is `/_next/*`. Query strings are never part of a route, because they are never stored. ## Who can see it Any member of the team, viewers included. Viewers can see the Alerts card but not change it. ## From the API `GET /v1/teams/{team}/projects/{project}/observability` returns the page's numbers: `range` (`1h`, `6h`, `24h` or `7d`, default `24h`), and optionally `route` (from the answer's `all_routes`), `status` and `region`. ```console $ curl -s "https://api.theorbits.app/v1/teams/acme/projects/storefront/observability?range=7d" \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` The answer has: | Field | | | --- | --- | | `totals`, `previous` | `requests`, `errors` (5xx), `p50_ms`, `p75_ms` and `p99_ms` for the range, and for the period before | | `buckets` | Oldest first: each one's `start`, `requests`, `errors`, `p75_ms`, `p99_ms` | | `routes` | The 20 busiest, with the same figures | | `statuses` | Requests by `2xx`, `3xx`, `4xx`, `5xx` | | `regions` | Requests per region | | `all_routes` | The 100 busiest routes, for the route filter | | `bucket_seconds`, `as_of` | The bucket size and when the numbers were worked out | A `503` means the logs can't be read for a moment; try again shortly. The full reference is at [API › Logs](https://docs.orbits.africa/api/logs). ## Related ::::cards :::card[Runtime logs]{href=/observe/runtime-logs} The requests and output behind every number here. ::: :::card[Alerts]{href=/observe/alerts} Be told when production is failing, slow or quiet. ::: :::card[Speed Insights]{href=/observe/speed-insights} How fast pages load in your visitors' browsers. ::: :::: --- # Analytics Source: https://docs.orbits.africa/observe/analytics Visitors, top pages, referrers, devices and your own custom events, counted without cookies and without storing IP addresses. Add `@useorbits/analytics` to your app and turn Analytics on for the project. Pro plan. ## How it works Analytics has two halves: 1. **A switch on the project.** Turning Analytics on tells your project's production addresses to serve Orbits' script, `/_orbits/analytics.js`, and to record what it sends. 2. **A small package in your app**, `@useorbits/analytics`. It loads that script from your site's own address. The script counts each page a visitor sees, single-page navigations included, and the custom events you send. The script sends to `/_orbits/e` on your own host, so there is nothing cross-site to allow and nothing for your app to handle: those requests never reach your app and don't count as its requests. Only **production** deployments are counted, never previews. :::info[Analytics is part of Pro] Turning Analytics on needs the team to be on [Pro](https://docs.orbits.africa/billing/plans). On Free, the switch answers with an upgrade prompt. If a Pro team goes back to Free, collection stops but the numbers already collected are kept, and come back when the team is on Pro again. ::: ## 1. Turn it on Open the project, choose **Analytics** and press **Turn on Analytics**. Owners, admins and members can turn it on or off; viewers can't. The project's addresses pick the change up within seconds. Until the first visit arrives, the page says **Waiting for the first visit** and shows the snippet to add. To turn it off later, use **Turn it off** at the foot of the page. While it's off, the script isn't served and nothing is recorded. ## 2. Install the package ```console $ npm install @useorbits/analytics ``` Then add it once, in the place your framework renders on every page. ::::tabs :::tab[Next.js] Put `` in the root layout. Pages are grouped by the route that served them (`/blog/[slug]`), not by each address. ```tsx title="app/layout.tsx" import { Analytics } from "@useorbits/analytics/next"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` With the Pages Router, render it in `pages/_app.tsx` instead. ::: :::tab[React] For Vite, React Router, TanStack Router, Remix and other React apps: ```tsx import { Analytics } from "@useorbits/analytics/react"; export function App() { return ( <> ); } ``` ::: :::tab[Vue and Nuxt] ```vue title="App.vue (app.vue in Nuxt)" ``` ::: :::tab[SvelteKit] ```ts title="src/routes/+layout.ts" import { injectAnalytics } from "@useorbits/analytics/sveltekit"; injectAnalytics(); ``` Pages are grouped by SvelteKit's route (`/products/[id]`). ::: :::tab[Astro] ```astro title="src/layouts/Base.astro" --- import Analytics from "@useorbits/analytics/astro"; --- ``` Astro 5 names the route that served each page, and View Transitions are counted too. ::: :::tab[Anything else] With a bundler, call `inject()` once in code that runs in the browser: ```ts import { inject } from "@useorbits/analytics"; inject(); ``` Without one, add the script itself. It's the same script the package loads: ```html ``` ::: :::: Deploy to production, and visits show on the **Analytics** tab within a minute. ## 3. Send custom events Count what matters to you, like sign-ups or orders, from anywhere in the browser: ```ts import { track } from "@useorbits/analytics"; track("Signed up", { plan: "pro", seats: 3 }); ``` - Properties are flat: strings, numbers, booleans or `null`, up to 20 of them. - Event names, property keys and string values are cut at 255 characters. The **Events** panel lists events by how often they were sent. Pick one to see the properties sent with it, each with its ten commonest values. Events can be sent from the browser only; there is no server-side `track()` yet. To count a page view yourself, such as a step in a wizard that keeps the same address, call `pageview({ path: "/checkout/payment" })`. ## What counts as a page view - **The page a visitor lands on**: counted, with the referrer if there is one. - **Each `history.pushState`, and back or forward**: counted, so client-side routing is covered. The Next.js, SvelteKit and Astro components report their own navigations instead, with the route. - **The same path twice in a row**: counted once. Query strings and hashes are left out. - **Browsers driven by a script, crawlers, bots and link previews**: not counted. - **Development**: nothing is sent. In a dev build or on `localhost` the package logs to the console instead. ## Options `` takes the same options as `inject()`: | Option | Default | | | --- | --- | --- | | `beforeSend` | | A function that gets each page view and event before it's sent. Return it, changed or not, or `null` to drop it. | | `mode` | `"auto"` | `"development"` logs to the console instead of sending; `"auto"` is development in a dev build or on `localhost`. | | `debug` | `false` | Log each page view and event the script sends. | | `scriptSrc` | `"/_orbits/analytics.js"` | Where the script is loaded from. | | `endpoint` | `"/_orbits/e"` | Where page views and events go. | Use `beforeSend` to keep private pages and codes out of your numbers: ```tsx { if (event.url.includes("/admin")) return null; return { ...event, url: event.url.replace(/\/invite\/[^/]+/, "/invite/[code]") }; }} /> ``` The Astro component can't take a function: set `window.orbitsAnalyticsBeforeSend` before it renders instead. ## Reading the page Pick a **Time range**: **24 hours** (by the hour), **7 days** or **30 days** (by the Lagos day). Each is compared with the span before it, such as today against yesterday. | Panel | | | --- | --- | | **Visitors** | Visitors and page views over the range. A bounce is a visitor who saw one page | | **Top pages** | By the route your framework named, or else the path with its ids grouped (`/products/8412` is `/products/[id]`) | | **Referrers** | Other sites that sent visitors. A visit nobody linked to has no referrer | | **Countries** | Empty for now: countries show once Orbits starts looking up where visits come from | | **Devices** | The kinds of device visitors used | | **Events** | Your custom events, most sent first | Lists keep their top ten. Any member of the team can read the page. ## Privacy: what is collected - **No cookies**, so there is no cookie banner to add for Analytics. - **No IP addresses and no browser strings are stored.** - **A visitor is a hash that changes every day.** It is made from a secret, the date in Lagos, the project, the visitor's address and their browser, and only the hash is kept. The same person counts once a day, and can't be followed from one day to the next, or from one project to another. - **Query strings and hashes** are left out of the page address. - **Bots, link previews, scripts and headless browsers** are dropped. - **No user ids.** Orbits doesn't keep an id for a visitor in the browser. ## From the API | Call | | | --- | --- | | `GET /v1/teams/{team}/projects/{project}/analytics?range=7d` | The page's numbers: `range` is `24h`, `7d` (default) or `30d`. Answers `{ "enabled": false }` while it's off | | `GET .../analytics/event?name=Signed%20up&range=7d` | One custom event, with how often it was sent, by how many visitors, and its properties | | `PUT .../analytics` with `{ "enabled": true }` | Turn it on or off. On Free, turning it on is `402` with `code: plan_required` | See [API › Insights](https://docs.orbits.africa/api/insights). ## Related ::::cards :::card[Speed Insights]{href=/observe/speed-insights} Core Web Vitals from real visits, with `@useorbits/speed-insights`. ::: :::card[Plans]{href=/billing/plans} What Pro includes. ::: :::: --- # Speed Insights Source: https://docs.orbits.africa/observe/speed-insights Core Web Vitals from real visits to your production site, on your visitors' own phones and networks, with the slowest routes and the elements behind them. Add `@useorbits/speed-insights` and turn it on for the project. Pro plan. ## How it works Speed Insights measures how fast your pages load and respond for the people actually using them. Like [Analytics](https://docs.orbits.africa/observe/analytics), it has two halves: 1. **A switch on the project.** Turning Speed Insights on makes your production addresses serve Orbits' script, `/_orbits/speed-insights.js`, and record what it sends. 2. **A small package in your app**, `@useorbits/speed-insights`, which loads that script from your site's own address. The script measures five Web Vitals with Google's `web-vitals` library and sends them together, in one report per page load, when the visitor leaves the page. Reports go to `/_orbits/e` on your own host; they never reach your app. Only **production** deployments are measured. :::info[Speed Insights is part of Pro] Turning Speed Insights on needs the team to be on [Pro](https://docs.orbits.africa/billing/plans). On Free, the switch answers with an upgrade prompt. If a Pro team goes back to Free, measuring stops; what was collected is kept and shows again on Pro. ::: ## 1. Turn it on Open the project, choose **Speed Insights** and press **Turn on Speed Insights**. Owners, admins and members can switch it; viewers can't. The change reaches your addresses within seconds. Until reports arrive, the page says Speed Insights is on and shows the snippet to add. **Turn it off** at the foot of the page stops it. ## 2. Install the package ```console $ npm install @useorbits/speed-insights ``` Add it once, where your framework renders on every page. ::::tabs :::tab[Next.js] Each page load is reported against the route that served it (`/blog/[slug]`). ```tsx title="app/layout.tsx" import { SpeedInsights } from "@useorbits/speed-insights/next"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` With the Pages Router, render it in `pages/_app.tsx` instead. ::: :::tab[React] For Vite, React Router, TanStack Router, Remix and other React apps: ```tsx import { SpeedInsights } from "@useorbits/speed-insights/react"; export function App() { return ( <> ); } ``` ::: :::tab[Vue and Nuxt] ```vue title="App.vue (app.vue in Nuxt)" ``` ::: :::tab[SvelteKit] ```ts title="src/routes/+layout.ts" import { injectSpeedInsights } from "@useorbits/speed-insights/sveltekit"; injectSpeedInsights(); ``` ::: :::tab[Astro] ```astro title="src/layouts/Base.astro" --- import SpeedInsights from "@useorbits/speed-insights/astro"; --- ``` ::: :::tab[Anything else] With a bundler, call `injectSpeedInsights()` once in code that runs in the browser: ```ts import { injectSpeedInsights } from "@useorbits/speed-insights"; injectSpeedInsights(); ``` Without one, add the script itself: ```html ``` ::: :::: Deploy to production. Reports show as real visitors browse. ## What's measured | Metric | What it tells you | Good | The element named | | --- | --- | --- | --- | | **LCP**, Largest Contentful Paint | When the main content appeared | 2.5 s or less | The largest element | | **INP**, Interaction to Next Paint | How quickly the page responds to taps and clicks | 200 ms or less | The one interacted with | | **CLS**, Cumulative Layout Shift | How much the layout jumps around while loading | 0.1 or less | The one that shifted most | | **FCP**, First Contentful Paint | When anything first appeared | 1.8 s or less | | | **TTFB**, Time to First Byte | How long the server took to start answering | 0.8 s or less | | LCP, INP, FCP and TTFB are in milliseconds; CLS is a score with no unit. Each report also carries the connection the visitor was on (4G, 3G and so on) where the browser says. ## Reading the page Choose a **Device**, **Mobile** (tablets count as mobile) or **Desktop**, and a **Time range**: **24 hours**, **7 days** (the default) or **30 days**. Every figure is the **75th percentile (p75)**: the value three in four page loads did better than. | Panel | | | --- | --- | | **Real experience score** | 0 to 100, from the p75s there are (below) | | Each metric | Its p75 against the good line | | **Largest paint over time** | LCP's p75, bucket by bucket | | **By route** | The most visited routes, ten at most, each with every vital's p75. **Slowest first** sorts them | | **What's slowing it** | The elements (as CSS selectors) most often behind LCP, INP and CLS, five each, with how often and their p75 | | Connections | LCP samples by the connection they were measured on | Routes are the ones your framework named (Next.js, SvelteKit and Astro report them), or else the path with its ids grouped (`/products/8412` is `/products/[id]`). ### How the score is worked out Each metric's p75 is scored the way Lighthouse scores it, 90 at its good line and 50 at its median, then weighted: | Metric | Weight | | --- | --- | | FCP | 15% | | LCP | 30% | | INP | 30% | | CLS | 25% | TTFB is shown, not scored. With no reports at all, there is no score. ## Options `` takes the same options as `injectSpeedInsights()`: | Option | Default | | | --- | --- | --- | | `sampleRate` | `1` | The share of page loads that report, from 0 to 1. On a busy site, `0.5` reports half. | | `beforeSend` | | A function that gets each report before it's sent. Return it, changed or not, or `null` to drop it. | | `mode` | `"auto"` | `"development"` measures nothing; `"auto"` is development in a dev build or on `localhost`. | | `debug` | `false` | Log each report the script sends. | | `scriptSrc` | `"/_orbits/speed-insights.js"` | Where the script is loaded from. | | `endpoint` | `"/_orbits/e"` | Where reports go. | ```tsx ``` The Astro component can't take a function: set `window.orbitsSpeedInsightsBeforeSend` before it renders instead. ## Privacy Speed Insights follows the same rules as Analytics: no cookies, no IP addresses stored, nothing sent in development, and bots and headless browsers left out. See [Analytics › Privacy](https://docs.orbits.africa/observe/analytics#privacy-what-is-collected). ## In the weekly summary When the team's [weekly summary](https://docs.orbits.africa/team/notifications) is on, it includes mobile Web Vitals from the busiest project that has Speed Insights. ## From the API | Call | | | --- | --- | | `GET /v1/teams/{team}/projects/{project}/speed-insights?device=mobile&range=7d` | The page's numbers. `{ "enabled": false }` while it's off | | `PUT .../speed-insights` with `{ "enabled": true }` | Turn it on or off. On Free, turning it on is `402` with `code: plan_required` | See [API › Insights](https://docs.orbits.africa/api/insights). --- # Alerts Source: https://docs.orbits.africa/observe/alerts Be told when production's error rate or response times cross a line you choose, or when its traffic stops. Rules are checked every minute, and fired and resolved notices go by email or to your team's signed webhook. ## What an alert watches An alert rule belongs to a project and watches **production**: the same requests as [Observability](https://docs.orbits.africa/observe/observability). Previews are never measured. Each rule has: | Field | | | --- | --- | | **Name** | Up to 60 characters, unique in the project, such as "Checkout slow" | | **Measure** | `error-rate`: 5xx answers as a share of requests, in %. `p75` or `p99`: response time in milliseconds. `requests`: requests a minute | | **Is above / Is below** | The direction. `requests` can be either; the others are always above | | **Threshold** | The line. An error-rate threshold must be under 100 | | **For at least** | The window: 1, 5, 10 or 30 minutes | | **Routes** | **This project** (every route) or **These routes**: up to 10 routes as Observability names them, a trailing `*` for a prefix, such as `/checkout, /api/checkout/*` | | **Send to** | Email, the team webhook, or both | | The switch | A rule that's off isn't checked | "Requests below 1 a minute for 10 minutes" is how you find out production stopped getting traffic. "Requests above" catches a spike. ## Create one 1. Open the project and choose **Observability**. 2. On the **Alerts** card, press **Create alert**. 3. Pick a measure, a threshold, how long, the routes and where to send it. 4. Press **Create alert**. The rule starts as **OK** and is first checked at the next :30 past the minute. Owners, admins and members create, edit, switch and delete rules; viewers see them but can't change them. ### The traffic warning `error-rate`, `p75` and `p99` need at least **20 requests in a window** before they say anything: one failure out of two requests isn't a 50% error rate worth waking someone for. While you fill in the form, Orbits looks at the last 24 hours and warns when your routes don't get that much, for example: > These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes. It's a warning, not a refusal: you can still save the rule, and it works once traffic grows. `requests` rules have no minimum. ## How rules are checked Every minute, at 30 seconds past, Orbits works each rule's measure out over its window, ending at the last whole minute. - **Fired**: when the value is past the line (above the threshold, or below it for a "below" rule), the rule goes from OK to **Firing** and its channels are told once. - **Resolved**: after **3 checks in a row** back on the right side of the line (or at it), it goes back to OK and its channels are told it resolved. This stops a value hovering at the line from firing every minute. A 30-minute rule resolves later, since its window holds on to the failure for a while. - **No repeats** while it stays firing. - **Too little traffic** (under 20 requests for `error-rate`, `p75` or `p99`) means the rule can neither fire nor resolve on that check. A firing rule still counts such a quiet check towards resolving, unless the few requests there were are still past the line. A rule that resolves this way says its traffic went too quiet to measure. - If Orbits can't read the logs for a minute, that minute is skipped and nothing changes. "Below" rules are also skipped when no logs have arrived from anywhere lately, so a delay on Orbits' side doesn't set them all off. **Editing, switching off or deleting a firing rule resolves it first**, so a receiver that opened an incident sees it close. Any change starts the rule again from OK. ## History Each rule's history lists when it fired and resolved, newest first, kept for 90 days. A resolve says why: | Reason | | | --- | --- | | Recovered | The value came back | | Quiet | Its traffic went too quiet to measure | | Changed | It was edited while firing | | Off | It was switched off while firing | | Deleted | It was deleted while firing | Each event also shows how every channel's notice went: still trying, delivered, or failed with the reason ("The webhook answered 500"). A notice is tried up to 5 times over about 30 minutes before it's marked failed. Deleting a rule deletes its history. A fired or resolved alert is also a line in the team's [activity feed](https://docs.orbits.africa/team/activity), and a firing alert shows in the bell. ## Channels ### Email To the team's owners, admins and members, the people who deploy. Viewers don't get alert email. There is no per-person opt-out yet. ### The team webhook One webhook per team, used by every rule that has **Team webhook** in **Send to**, from every project. Owners and admins set it under **Team › Settings › Alert webhook**; members and viewers can't see its address, only whether one is set. A rule can't pick the webhook until the team has one. To set it up: 1. Enter an `https` address on the public internet, with no user name or password in it. 2. Save. Orbits makes a **signing secret** (64 hex characters) and shows it **once**: copy it into your receiver, for example as `WEBHOOK_SECRET`. 3. Press **Send test event** to send a signed `alert.test` and see whether it was delivered, or what the receiver answered. **Rotate secret** makes a new one, shown once; the old one stops working at once, so update your receiver straight after. **Remove webhook** stops sending: notices still waiting fail with "The team has no webhook". Alerts can't go to Slack or Microsoft Teams yet; use email or the webhook. ## What the webhook receives Each notice is a JSON `POST` with these headers: | Header | | | --- | --- | | `X-Orbits-Event` | `alert.fired`, `alert.resolved` or `alert.test` | | `X-Delivery-Id` | The same on every retry of one notice, so you can drop a repeat | | `X-Signature-256` | `sha256=` and the hex HMAC-SHA256 of the raw body, keyed with the secret | | `User-Agent` | `Orbits-Alerts/1` | ```json title="alert.fired" { "type": "alert.fired", "delivery_id": "adl_…", "event_id": "…", "at": "2026-11-10T09:15:30Z", "reason": null, "value": 8, "summary": "8% errors over 5 minutes", "measure": { "requests": 250, "errors": 20 }, "rule": { "id": "alr_…", "name": "Checkout errors", "metric": "error-rate", "direction": "above", "threshold": 5, "window_minutes": 5, "routes": ["/checkout", "/api/checkout/*"] }, "project": { "id": "prj_…", "slug": "storefront", "name": "Storefront" }, "team": { "id": "team_…", "slug": "acme" }, "url": "https://orbits.africa/…/observability" } ``` `alert.resolved` has the same shape with a `reason`. `alert.test` carries only `type`, `delivery_id`, `at` and `team`. `url` links to the project's Observability page. Answer with any `2xx` and the notice is delivered. Anything else, or no answer within 10 seconds, is tried again. Redirects aren't followed, and an address that isn't on the public internet is refused. Check the signature before trusting a request. The webhooks of [Integrations](https://docs.orbits.africa/team/integrations#verify-the-signature) are signed the same way, and that page has verification code for Node and Python. ## From the CLI and the API ```console $ orbits alerts create "Errors" --metric error-rate --threshold 5 --window 5 $ orbits alerts create "Quiet" --metric requests --direction below --threshold 10 --window 30 $ orbits alerts ls $ orbits alerts disable $ orbits alerts events ``` | Call | Who | | --- | --- | | `GET /v1/teams/{team}/projects/{project}/alerts` | Any member. Rules, their state and `webhook_configured` | | `POST .../alerts` | Owner, admin, member. Create a rule | | `POST .../alerts/preview` | Owner, admin, member. The traffic a draft rule would see: `median_requests`, `minimum_requests`, `value` | | `PATCH .../alerts/{alert}`, `DELETE .../alerts/{alert}` | Owner, admin, member | | `GET .../alerts/{alert}/events` | Any member. The history | | `GET /v1/teams/{team}/alert-channels` | Owner, admin. The webhook's address and the secret's last four characters | | `PUT .../alert-channels/webhook`, `DELETE ...` | Owner, admin. Set (`rotate_secret: true` for a new secret) or remove it | | `POST .../alert-channels/webhook/test` | Owner, admin. Send `alert.test` | ```json title="POST .../alerts" { "name": "No traffic", "metric": "requests", "direction": "below", "threshold": 1, "window_minutes": 10, "routes": [], "channels": ["email", "webhook"] } ``` A `422` names the field that's wrong. The full reference is at [API › Alerts](https://docs.orbits.africa/api/alerts). --- # Feature flags Source: https://docs.orbits.africa/features/flags Ship code switched off, then turn it on for your team, a share of visitors or everyone, per environment, without a redeploy. Flags live in your project's Flags tab and your app checks them with `@useorbits/flags`. ## How flags work A flag is a named switch or value that your code checks. You manage flags in the project's **Flags** tab; your app checks them with the `@useorbits/flags` package. Checks happen **inside your app**, not over the network. The package fetches your environment's flags once, answers every check from memory, and refreshes them in the background every few seconds. A change in the Flags tab reaches running deployments within seconds, with no redeploy. ## Create a flag 1. Open the project and choose **Flags**, then **Create flag**. 2. Give it a **key**: lowercase letters, digits and single dashes, up to 48 characters, unique in the project, like `new-checkout`. This is what your code checks. 3. Add a description (up to 120 characters) if it helps. 4. Pick its **Type**: - **Boolean**: on or off. Starts off in each environment, at a 100% rollout, with no rules, unless you turn it on. - **String** or **Number**: serves a value. Give it a value for each environment. 5. Press **Create flag**. Owners, admins and members create, change and delete flags. Viewers can see them. The key and type never change. To change either, make another flag. You can edit the description later. ## Environments Every flag has a setting for each of the three environments, and they're independent: | Environment | Read by | | --- | --- | | **Production** | Production deployments | | **Preview** | Preview deployments | | **Development** | Your machine, with the development key (see [local development](#local-development)) | So you can turn a flag on in Preview, try it on a branch's preview, and only then turn it on in Production. In each environment, a **boolean** flag has a switch (**On** or **Off**) and a **rollout**: the share of ids it's on for, from 1% to 100%. A **string** or **number** flag has a value. ## Targeting rules Rules come before the switch and the rollout: the first rule that matches decides. Each environment can have up to 20. A rule is: | Part | | | --- | --- | | **What to check** | An attribute your code passes to `flag()`: `email`, `id`, `plan`, `country`, or a path like `user.plan` | | **How to compare** | `equals`, `not_equals`, `one_of`, `starts_with`, `ends_with` or `contains`. `one_of` takes several values separated by commas; the others take one | | **What a match gets** | On or off for a boolean flag; a value for a string or number flag | Comparisons ignore case. An attribute your code didn't pass matches nothing. For example, "Email ends with `@kudi.ng`, gets On" turns a new feature on for your own team only. ### How a check is decided For each check, in order: 1. The **first matching rule** decides. 2. Otherwise a **boolean** flag that's **off** is off. 3. Otherwise a boolean flag is **on for its rollout's share of ids**. The same id always gets the same answer, and stays in as the share grows. Without an id, only a 100% rollout is on. 4. A **string** or **number** flag serves its value. The share is a stable hash of the flag's key and the id, so two flags at 25% don't pick the same quarter of your users. ## Use flags in your code ```console $ npm install @useorbits/flags ``` Every deployment gets its environment's key as `ORBITS_FLAGS`, and the API's address as `ORBITS_API_URL`, so there's nothing to configure. A variable you set yourself with the same name wins. In server code (a Server Component, a route handler, an API, a worker): ```tsx import { flag } from "@useorbits/flags"; export default async function Checkout() { const user = await currentUser(); if (await flag("new-checkout", { id: user.id, email: user.email })) { return ; } return ; } ``` The second argument is the **context** that rules and rollouts read. String and number flags return their value. Pass a default for when the flag doesn't exist yet or Orbits can't be reached; a boolean flag's default is `false`: ```ts const backend = await flag("search-backend", {}, "typesense"); const pageSize = await flag("page-size", {}, 20); ``` To get every flag at once, such as to hand them all to a page: ```ts import { flags } from "@useorbits/flags"; const all = await flags({ id: user.id }); // { "new-checkout": true, "search-backend": "typesense" } ``` Flags are for server code. Checking flags in client components isn't available yet. ### Options The shared client reads `ORBITS_FLAGS` and `ORBITS_API_URL`. To set them yourself, call `configure` before the first check: ```ts import { configure } from "@useorbits/flags"; configure({ key: process.env.MY_FLAGS_KEY, refreshMs: 10_000 }); ``` | Option | Default | | | --- | --- | --- | | `key` | `ORBITS_FLAGS` | The environment's key | | `apiUrl` | `ORBITS_API_URL` | Orbits' API | | `refreshMs` | `5000` | How old the flags may get before they're fetched again in the background | | `report` | `true` | Report which flags were checked, for "Seen in the last 24 hours" | | `debug` | `false` | Log fetches and reports | For more than one key in a process, make your own client: `new FlagsClient({ key })`, then `client.flag(...)`. ## Local development On your machine there's no deployment to hand you a key. Copy the **Development** key from the Flags tab (under **On your machine**) into `.env.local`: ```sh title=".env.local" ORBITS_FLAGS=ofl_… ``` Your app then reads Development's flags. Without a key, every flag gets its default, and the package says so once in the console. Owners, admins and members can see the keys; viewers can't. A key reads its environment's flags and reports checks, and does nothing else. Treat it like any other secret all the same. Keys can't be rotated one at a time yet. ## A flag's page Pick a flag to see each environment's setting and rules, and: - **History**: every change, newest first (the last 50), with who made it. - **Seen in the last 24 hours**: for each environment, how many checks there were and how many different ids they were for, as your deployments reported them. **Delete flag** removes it everywhere. Your deployments stop getting it on their next refresh, and code that checks it gets the default it passes. ## What the package calls You don't need these to use flags; they're what `@useorbits/flags` does for you, in case you write your own client. Both take the environment's key as `Authorization: Bearer ofl_…`, not an API token. ### `GET /v1/flags/definitions` The environment's flags, for the package to evaluate: ```json { "environment": "production", "version": "…", "flags": { "new-checkout": { "type": "boolean", "on": true, "rollout": 25, "value": null, "rules": [ { "attribute": "email", "operator": "ends_with", "values": ["@kudi.ng"], "serve": true } ] } } } ``` Send `If-None-Match` with the last `ETag` and you get `304` while nothing has changed. That's how the package refreshes cheaply every few seconds. A wrong key is `401`. ### `POST /v1/flags/exposures` About once a minute while flags are being checked, the package reports how many times each flag was checked and for which ids: up to 200 flags a report, 500 ids per flag. Each id is sent as the **first 16 hex characters of its SHA-256**, never as it was, so no user id leaves your app. Orbits keeps them by the hour for two days, for "Seen in the last 24 hours". Turn reporting off with `configure({ report: false })`. Neither call counts against the API's [rate limits](https://docs.orbits.africa/api/rate-limits). ## From the CLI and the API ```console $ orbits flags create new-checkout --type boolean --description "One-page checkout" $ orbits flags set new-checkout --environment preview --on $ orbits flags set new-checkout --environment production --on --rollout 25 $ orbits flags rules add new-checkout --environment production --attribute email \ --operator ends_with --values @kudi.ng --serve true $ orbits flags ls ``` The web app's calls are under `/v1/teams/{team}/projects/{project}/flags`: list, create, get, change the description, delete, set an environment (`PUT .../flags/{flag}/environments/{environment}` with `on`, `rollout` or `value`), and add, change or remove rules. `GET .../flag-keys` returns the three keys. See [API › Flags](https://docs.orbits.africa/api/flags). --- # Workflows Source: https://docs.orbits.africa/features/workflows Durable workflows in your own code with `@useorbits/workflows`. Steps that save their results, retry on failure, survive crashes and deploys, sleep for days or wait for an event, with every run on the project's Workflows tab. ## What a workflow is A workflow is a function in your app made of **steps**. Orbits keeps each run and calls your app for one step at a time. When a step finishes, its result is saved; when the run carries on, finished steps answer from their saved results, so the run picks up where it left off, after a crash, a deploy or a week's sleep. You don't run a queue or a server of your own for it. Each run shows on the project's **Workflows** tab, with every step's time, result and error, and **Run now**, **Retry** and **Cancel**. :::note[Which apps can run workflows] Workflows run on **production** deployments of apps with a server on Node: Next.js, Node or Elysia. Static sites can't run them, and neither can workers or apps built from your own container image yet. ::: ## 1. Install ```console $ npm install @useorbits/workflows ``` ## 2. Write a workflow ```ts title="workflows/sync-stock.ts" import { workflow } from "@useorbits/workflows"; export const syncStock = workflow( "sync-stock", { schedule: "*/15 * * * *", description: "Pulls the supplier feed into inventory" }, async ({ input, step, sleep }) => { const rows = await step("fetch-supplier-feed", () => fetchFeed()); const valid = await step("parse-csv", () => parse(rows)); await step("update-inventory", () => updateStock(valid)); if (valid.skipped.length) { await step("notify-slack", () => notify(valid.skipped)); } await sleep("1 hour"); await step("write-report", () => writeReport(valid)); }, ); ``` Each `step()` runs its function once. Its return value is saved, and from then on the step returns that. | Option | Default | | | --- | --- | --- | | `description` | | A line on the Workflows tab | | `schedule` | | A five-field cron, in UTC | | `event` | | The event that starts it. Use this or `schedule`, not both | | `retries` | `2` | Attempts after the first, for each step, up to 10 | ### When a step fails A step that throws is tried again with backoff: after 10 seconds, then a minute, then 5 minutes, up to `retries` times. While it waits, the step shows **Running** with its last error and when the next attempt is due. After the last attempt the run **fails**. **Retry failed step** on the run's page starts it again from that step. ## 3. Serve it Orbits runs your workflows through one endpoint in your app, `/.well-known/orbits/workflows`. In Next.js: ```ts title="app/.well-known/orbits/workflows/route.ts" import { serve } from "@useorbits/workflows"; import { syncStock } from "@/workflows/sync-stock"; import { sendOrderEmails } from "@/workflows/send-order-emails"; export const { GET, POST } = serve([syncStock, sendOrderEmails]); ``` `serve()` returns standard `Request` to `Response` handlers, so mount them at the same path in any framework that takes those, such as Elysia, Hono or SvelteKit: ```ts const { GET, POST } = serve([syncStock]); app.get("/.well-known/orbits/workflows", ({ request }) => GET(request)); app.post("/.well-known/orbits/workflows", ({ request }) => POST(request)); ``` Only Orbits reaches this endpoint. Orbits' edge keeps the path off the internet on every address, and each call carries your deployment's `ORBITS_WORKFLOWS` key, which Orbits sets for you and the package checks. **Deploy to production.** Once the deployment is live, Orbits reads its list of workflows from this endpoint, and they appear on the Workflows tab. A project's workflows are always those of its latest production deployment. ## Start a run | How | Set it with | Its `input` | | --- | --- | --- | | A schedule | `schedule: "0 2 * * *"`, a five-field cron in UTC | `{}` | | An event | `event: "order.paid"`, then `trigger("order.paid", data)` from your code | `data` | | By hand | **Run now** on the Workflows tab | The JSON you type | ```ts import { trigger } from "@useorbits/workflows"; await trigger("order.paid", { order: order.id, email: order.email }); ``` A schedule starts at most one run of a workflow a minute. Runs belong to production: an event sent from a preview or from your machine is accepted and does nothing. ## Sleep and wait for events ```ts const sendOrderEmails = workflow("send-order-emails", { event: "order.paid" }, async ({ input, step, sleep, waitFor }) => { await step("send-receipt", () => sendReceipt(input.order)); const shipped = await waitFor<{ tracking: string }>("order.shipped", { timeout: "3 days" }); if (shipped) await step("send-tracking", () => sendTracking(input.order, shipped.tracking)); await sleep("7 days"); await step("ask-for-review", () => askForReview(input.order)); }); ``` - `sleep()` takes `"30s"`, `"15 minutes"`, `"2 hours"`, `"1 day"` or milliseconds. - `waitFor(event)` resumes when `trigger(event, data)` is sent, and returns `data`. If its `timeout` passes first, it returns `null`. Neither holds a server open: the run is simply called again when it's time. ## The one rule: same steps, same order A run resumes by running your function again from the top, with finished steps answering from their saved results. So the code **outside** steps must reach the same steps in the same order every time. Put anything that can change inside a step: the clock, randomness, reading a database or an API. ```ts // Don't: a different answer on each replay if (Math.random() < 0.5) await step("a", doA); // Do: decided once, inside a step const pick = await step("pick", () => Math.random() < 0.5); if (pick) await step("a", doA); ``` If a run's steps come back in another order, for example because you deployed code that changed under a running workflow, the run fails with an error that says so, rather than guessing. A run uses whichever deployment is production when it's called, so keep that in mind when you change a workflow that has long sleeps. ## Runs: the Workflows tab The tab lists each workflow with its trigger ("Every 15 minutes", "When order.paid happens"), its last run and its success rate over the last 7 days, then **Recent runs**, the 50 newest. A run is **Running**, **Succeeded**, **Failed** or **Canceled**. Open one to see its trigger, who started it, the deployment it ran on, its input and output, and each step: | Step state | | | --- | --- | | Running | Underway, or waiting for its next attempt after an error | | Succeeded | Done; its result is saved | | Failed | Out of attempts | | Waiting | A sleep or a `waitFor` not over yet, or a step this run hasn't reached | | Skipped | A step the run never reached because it failed or was canceled | | Canceled | Stopped by **Cancel run** | Steps the run hasn't reached yet are shown from the workflow's last successful run, so you can see what's still to come. - **Run now** starts a run on production with the input you give (any JSON, up to 256 KB). It's picked up within seconds. It needs a production deployment that lists the workflow. - **Cancel run** stops a running run. Your app isn't called for it again; a step already running finishes, and its result is dropped. - **Retry failed step** carries a failed run on from the step that failed, with a fresh set of attempts. Earlier steps keep their results. Owners, admins and members can run, cancel and retry. Viewers can look. ## Try it locally `runLocally()` runs a workflow to the end in your own process: steps run once each, sleeps are skipped, and `waitFor()` gets the events you pass. It's handy in tests. ```ts import { runLocally } from "@useorbits/workflows"; const result = await runLocally(sendOrderEmails, { order: "ord_1" }, { events: { "order.shipped": { tracking: "GIG-1" } } }); // { state: "succeeded", output: …, steps: [...] } ``` ## Limits | | | | --- | --- | | A step's result | 256 KB at most, as JSON | | A run's input, an event's data | 256 KB at most | | A step's time | 5 minutes to finish | | Retries per step | Up to 10 (2 by default) | | Event names | Letters, digits and `. _ : -`, starting with a letter or digit, up to 100 characters | ## What the package calls `trigger(name, data)` sends `POST /v1/workflows/events` with the deployment's key as `Authorization: Bearer owf_…` (from `ORBITS_WORKFLOWS`, not an API token): ```json { "name": "order.paid", "data": { "order": "ord_1", "email": "ada@example.com" } } ``` It starts every workflow the production deployment lists with that `event`, with `data` as the input, and wakes runs waiting for it in `waitFor`. The answer is `202`, with what it started and woke. A wrong key is `401`. This call doesn't count against the API's [rate limits](https://docs.orbits.africa/api/rate-limits). ## From the CLI and the API ```console $ orbits workflows ls $ orbits workflows run send-digest --input '{"week":45}' $ orbits workflows runs $ orbits workflows retry ``` The web app's calls are `GET /v1/teams/{team}/projects/{project}/workflows`, `POST .../workflows/{workflow}/runs`, `GET .../workflows/runs/{run}`, and `POST .../runs/{run}/cancel` and `.../retry`. See [API › Workflows](https://docs.orbits.africa/api/workflows). --- # Sandboxes Source: https://docs.orbits.africa/features/sandboxes Short-lived development machines for a project, with a terminal in the browser and a preview address your team can open. Part of the Pro plan. ## What a sandbox is A sandbox is a small machine that belongs to a project: somewhere to try an upgrade, seed test data or run a script without touching your deployments. You start one from the project's **Sandboxes** tab, the [CLI](https://docs.orbits.africa/cli) or the [API](https://docs.orbits.africa/api/sandboxes), work in it through a terminal in the browser, and stop it when you're done. Sandboxes are part of the **Pro** plan. On Free, starting one answers with a plan-required error ([Plans](https://docs.orbits.africa/billing/plans)). ## Starting one Choose: | Setting | Options | | --- | --- | | **Name** | Lowercase letters, digits and single dashes, up to 40 characters, unique among the project's live sandboxes. | | **Runtime** | `node22`, `python312` or `go123`. | | **Size** | `small`: 0.5 vCPU, 512 MB of memory, 2 GB of disk. `large`: 1 vCPU, 2 GB of memory, 4 GB of disk. | | **Clone the repository** | Checks out the project's repository at `main`. Off gives an empty machine. | | **Copy variables** | Copies the project's **Preview** [environment variables](https://docs.orbits.africa/deploy/environment-variables) in. | | **Stop after** | 10, 30, 60 or 120 idle minutes before it suspends itself. | A new sandbox is `starting`, then `running` once it is up. ```console $ orbits sandboxes create try-upgrade --runtime node22 --clone --env ``` A team can run only a few sandboxes at once. The Sandboxes tab shows how many are running out of the most allowed. Starting one past that is refused until you stop another. ## Working in it - **Terminal.** The sandbox's page has a terminal in the browser, with what it printed while booting and running. - **Preview address.** Whatever listens on **port 3000** gets an address that only members of your team can open. - **Usage.** The page shows CPU, memory and disk against the size's limits. Over the API, the terminal is a WebSocket. A browser's WebSocket can't send a token, so you first ask for a **terminal ticket** (`POST …/sandboxes/{sandbox}/terminal-ticket`), which is good for 60 seconds, and open the socket with it. The SDKs return the ticket; they don't open the socket. ## Stopping, resuming and deleting - **Stop** suspends the sandbox: CPU and memory are freed and the disk is kept. Going idle for the *Stop after* time does the same, so a timeout never loses your work. - **Start** resumes a stopped sandbox from its disk. It counts against the team's running limit again. - **Delete** removes the machine and its disk. It can't be undone. ```console $ orbits sandboxes stop try-upgrade $ orbits sandboxes start try-upgrade $ orbits sandboxes rm try-upgrade ``` Owners, admins and members can manage sandboxes; viewers can only see them. --- # Teams and roles Source: https://docs.orbits.africa/team/teams-and-roles A team owns projects, domains, integrations and the plan. Create one, invite people as owners, admins, members or viewers, see who is active, and remove people or leave. Owners can delete the team. ## What a team is Everything on Orbits belongs to a team: its projects and their deployments, domains and Orbits DNS zones, integrations, API tokens, alerts and the [plan](https://docs.orbits.africa/billing/plans). You can belong to several teams; the team switcher at the top of the web app moves between them. Each team has its own members, roles and security rules. ## Create a team You create your first team when you sign up. To make another, open the team switcher and choose **Create a team**. You need: - **Team name**: what people see. - **Team URL** (the slug): the team's address in the web app, `orbits.africa/`. 3 to 40 characters: lowercase letters, digits and dashes, starting and ending with a letter or digit. It must be unique across Orbits, and a few words the web app uses for its own pages, such as `api`, `admin`, `settings`, `login` and `docs`, are reserved. You can invite up to 20 teammates in the same step. You become the team's **owner**. To change the name or URL later, go to **Team › Settings › General**. Old links to your dashboard stop working if you change the URL. The team's id (`team_…`) never changes, and the API accepts either. The **Default region** is Abuja (`abj-1`), the only region. ### Team avatar On **Settings › General**, upload a square image (at least 256 px works best) and crop it. PNG, JPEG or WebP; the source can be up to 10 MB, and the cropped avatar is at most 150 KB. Owners and admins can change it. ## Roles Every member has one role in the team. | Role | In short | | --- | --- | | **Owner** | Everything, including billing, members and deleting the team | | **Admin** | Everything an owner can, except billing, deleting the team and handling other owners and admins | | **Member** | Create projects, deploy, manage domains, variables, flags and alerts | | **Viewer** | See projects, deployments and logs. Can't change anything | ### What each role can do | | Owner | Admin | Member | Viewer | | --- | --- | --- | --- | --- | | See projects, deployments, logs, observability, analytics, activity | Yes | Yes | Yes | Yes | | Create projects | Yes | Yes | Yes | No | | Deploy, redeploy, cancel, promote, roll back | Yes | Yes | Yes | No | | Add, change, reveal and pull environment variables | Yes | Yes | Yes | Keys only | | Add, change and remove domains and DNS records | Yes | Yes | Yes | No | | Create and change alerts, flags; run workflows; switch Analytics and Speed Insights | Yes | Yes | Yes | No | | Change project settings, pause, delete a project | Yes | Yes | No | No | | Move a project to another team | Yes | Yes | No | No | | Team settings, security rules and notification switches | Yes | Yes | No | No | | API tokens, integrations and the alert webhook | Yes | Yes | No | No | | Invite people and manage invites | Yes | Yes | If allowed | No | | Change roles and remove people | Yes | Members and viewers | No | No | | Make someone an owner or admin | Yes | No | No | No | | Pay for Pro, cancel or resume it, see invoices | Yes | No | No | No | | Delete the team | Yes | No | No | No | | Get the team's emails (failed deploys, alerts, domain problems) | Yes | Yes | Yes | No | Moving a project to another team also needs you to be an owner of the team it's going to. :::note[Admins in the web app] The web app's role menus offer Owner, Member and Viewer. The admin role exists and works everywhere; it is given through the [API](https://docs.orbits.africa/api/teams) (`PATCH /v1/teams/{team}/members/{user}` with `role: admin`), by an owner. ::: A team always keeps at least one owner. Someone who isn't a member of a team gets "not found" for it, never "forbidden", so a team's name isn't given away. ## Invite people On **Team › Members**, enter one or more email addresses (up to 20 at a time, or paste a list), then pick a role. Each person gets an email with a link to join. **Invites expire after 7 days.** - Addresses that already belong to a member, or already have a pending invite, are skipped. - Pending invites show in the member list. **Resend** emails a fresh link and renews the 7 days; the old link stops working. **Revoke invite** takes it back. - You can also make a **reusable link** for a role and share it yourself. Anyone with the link can join until it expires or is revoked. An email invite can only be accepted by someone signed in with that email address. Someone without an account signs up from the invite page first. ### Who can invite Set under **Team › Settings › Security › Who can invite people**: | Setting | Who can invite | | --- | --- | | **Owners only** (the default) | Owners and admins | | **Owners and members** | Members too, but only as a member or a viewer | Viewers can never invite. Only an owner can invite someone as an owner or admin. ## The member list **Team › Members** lists active members, then pending invites. Search by name or email. Each row shows the person's role, whether they have [two-factor](https://docs.orbits.africa/team/security) on, and **Last active**: - **Active now** while they have the team open. - Otherwise, when they last used this team, to the minute. - **Never** if they haven't used the team since Orbits started recording it. Last active counts the person using the team in the web app or with their own session. Work done with an [API token](https://docs.orbits.africa/team/api-tokens) doesn't count: a script isn't the person. ## Change a role From the member's row menu, pick a new role. Owners and admins can move people between member and viewer; only an owner can make someone an owner or admin, or change an owner's or admin's role. The last owner can't be demoted: make someone else an owner first. ## Remove someone, or leave - **Remove** from a member's row: owners and admins can remove members and viewers; only an owner can remove an owner or admin. - **Leave** the team from your own row. You can leave even when the team requires two-factor and you don't have it on. The last owner can't leave or be removed. Make another member an owner first. When someone leaves or is removed, their [API tokens](https://docs.orbits.africa/team/api-tokens) for the team stop working at once, and stay dead if they rejoin. :::info[Handing over ownership] A dedicated "transfer ownership" action isn't available yet. To hand a team over, make the other person an owner, then change your own role or leave. ::: ## Delete a team On **Team › Settings › General**, under **Danger zone**, press **Delete team** and type the team's URL to confirm. Only owners can, and it can't be undone. What goes, in order: 1. Its Git connections. GitHub's app is uninstalled from the account, and GitLab and Bitbucket webhooks are removed. If Orbits can't do this, nothing is deleted and you can try again. 2. Its domains and Orbits DNS zones. 3. Every project, with its deployments, environment variables and alerts. Deployed apps stop being served. 4. Its activity, alert webhook and notifications. 5. The team, with its members, pending invites and avatar. If the team is on **Pro**, the plan ends with it, **with no refund**: nothing is charged again and the saved card is forgotten. Invoices already paid are kept as the record of the payment. ## From the API The team calls are under `/v1/teams` and `/v1/teams/{team}/members` and `/invites`. See [API › Teams](https://docs.orbits.africa/api/teams). API tokens can read the team, but can't manage members or invites, change security rules or delete the team. --- # API tokens Source: https://docs.orbits.africa/team/api-tokens Tokens let the CLI, CI and your own scripts act on a team without a browser. Make one under Team › Settings › API tokens, choose full or read-only access and an expiry, limit it to one project if you like, and copy the secret, which is shown once. ## What a token is An API token is a credential for the [CLI](https://docs.orbits.africa/cli), CI pipelines, the [SDKs](https://docs.orbits.africa/sdks) and your own scripts. It looks like this: ```text orb_live_8hTq2vXk9mPz4RwLc7NdYs1bGfJe6aUo ``` `orb_live_` and 32 more characters. A token: - **belongs to one team**, and reaches only that team; - **acts as the person who made it**, with their role in the team; - is **a CLI or CI credential, not a login**: it can't reach your account, sign-in or the team's most sensitive settings (see [what a token can't do](#what-a-token-cant-do)). Treat tokens like passwords. Tokens act as you in the CLI and in CI. ## Create a token Owners and admins manage the team's tokens, signed in to the web app. 1. Go to **Team › Settings › API tokens** and press **Create token**. 2. **Name** it after where it will run, like `github-actions` or `ada-laptop`: 1 to 40 characters, letters, numbers, dots, dashes and underscores, starting with a letter or number. Names are unique among the team's active tokens. 3. Pick its **Access**: - **Full access**: deploy, change settings and domains. - **Read only**: see projects, deployments and logs. 4. Pick its **Projects**: **All projects**, or one project. A token limited to a project reaches only that project: listing the team's projects or deployments shows just that one, and other team-wide pages (domains, usage, activity, settings) refuse it. 5. Pick when it **Expires**: **In 30 days**, **In 90 days**, **In a year** or **Never**. 6. Press **Create token**, then **Copy token**. :::warning[You see the secret once] Orbits keeps only a hash of the token, so it can't show it to you again. Put it somewhere safe straight away, like your CI's secrets. If you lose it, revoke it and make another. ::: A team can have **at most 50 active tokens**. Creating and revoking a token are both lines in the team's [activity feed](https://docs.orbits.africa/team/activity). ## The token list The **API tokens** card lists every token that isn't revoked, newest first: | Column | | | --- | --- | | **Name** | The name you gave it | | Hint | `orb_live_••••3f9a`: the last four characters, so you can tell tokens apart | | **Access** | Full access or Read only, and the project it's limited to, if any | | **Created** | When, and by whom: the person it acts as | | **Last used** | When it was last used (to the minute) and by which client, such as `orbits-cli/0.4.1`. "It hasn't been used yet" until its first request | | **Expires** | The date, or "It doesn't expire" | An expired token stays in the list, marked with its expiry, until someone revokes it. It answers `401` from the moment it expires. ## Revoke a token Press **Revoke token** on its row. It stops working at once (its next request is a `401`) and leaves the list. Revoke a token as soon as it might have leaked, then make a new one. ## Full and read-only | | Full access | Read only | | --- | --- | --- | | Methods | Any | `GET` and `HEAD` only | | Read projects, deployments, logs, usage, activity | Yes | Yes | | Deploy, promote, roll back, change settings and domains | Yes | No | | Read environment variable values (reveal, `orbits env pull`) | Yes | No | A read-only token can see which variables exist, but never their values: revealing and pulling values are writes. A read-only token answers `403` "This API token is read-only" to anything else. ## What a token can't do Some things are never a token's, whatever its access. They need a person signed in to the web app: - signing in, and anything about your account (`/v1/auth/...`, `/v1/me/...`); - creating teams and accepting invites; - **managing API tokens**; - **deleting the team**; - the team's **security rules**: two-factor, sign-in methods, session length, who can invite; - **members and invites**; - **moving a project to another team**; - **Git and notification integrations** (listing them is fine); - **paying for, cancelling or resuming Pro** (tokens can read the billing state, never change it). These answer `403` with a sentence that says so, such as "API tokens can't manage integrations". Outside its team, a token can only call `GET /v1/me`, `GET /v1/teams`, `GET /v1/templates` and `GET /v1/operations/{id}`, and those show it only its own team (and project, if it's limited to one). ## When a token stops working - **It's revoked, or it expires.** `401`. - **Its maker leaves the team, or is removed.** The token acts as that person, so it stops at once. It stays dead even if they rejoin: tokens made before someone's current membership began never work again. - **The team requires two-factor and its maker has it off.** The team's [two-factor rule](https://docs.orbits.africa/team/security) applies to the person a token acts as, so their tokens are refused until they turn two-factor on. The team's sign-in method and session-length rules are about browser sessions, so they don't affect tokens. ## Use a token Send it as a bearer token: ```console $ curl -s https://api.theorbits.app/v1/teams/acme/projects \ -H "Authorization: Bearer $ORBITS_TOKEN" ``` See [API › Authentication](https://docs.orbits.africa/api/authentication). ### With the CLI On a machine without a browser, pass the token on standard input: ```console $ orbits login --with-token < token.txt $ orbits whoami ``` In scripts and CI, set `ORBITS_TOKEN` instead. It is used in place of any stored sign-in, and nothing is written to disk: ```console $ export ORBITS_TOKEN=orb_live_… $ orbits --project storefront deploy ./dist --no-logs ``` On your own computer, `orbits login` signs you in through the browser instead, and makes a token for the CLI for you. ### In GitHub Actions Save the token as a repository secret named `ORBITS_TOKEN`, then: ```yaml title=".github/workflows/deploy.yml" - name: Deploy to Orbits env: ORBITS_TOKEN: ${{ secrets.ORBITS_TOKEN }} run: orbits --project storefront deploy ./dist --no-logs ``` Give CI the narrowest token that works: limited to the one project, read-only if it only reads, and with an expiry. ## Rate limits Each token has its own budget, apart from its maker's: **300 requests a minute**, in bursts of up to 100. The team's budget of 6,000 a minute is shared by its members and its tokens together. Over a limit the API answers `429` with `Retry-After`. See [rate limits](https://docs.orbits.africa/api/rate-limits). ## From the API Owners and admins, signed in (a token can't manage tokens): | Call | | | --- | --- | | `GET /v1/teams/{team}/tokens` | The list | | `POST /v1/teams/{team}/tokens` | Create one. Body: `name`, `access` (`full` or `read`), `expires` (`30`, `90`, `365` or `never`) and optionally `project`. The answer's `secret` is the only time you see it | | `DELETE /v1/teams/{team}/tokens/{token}` | Revoke one | Creating a token ignores `Idempotency-Key`: each call makes a new token, so a retry never hands back an old secret. See [API › Teams](https://docs.orbits.africa/api/teams). --- # Notifications Source: https://docs.orbits.africa/team/notifications Choose which events reach your team by email and Slack, see what needs you in the bell, and get a weekly summary every Monday. Microsoft Teams and webhooks pick their own events. ## Where notifications go | Where | What decides it | | --- | --- | | **Email** | The team's switches in **Settings › Notifications** | | **Slack** | The Slack switch for each event in **Settings › Notifications**, and the channel the [Slack page](https://docs.orbits.africa/team/integrations#slack) picks for it | | **Microsoft Teams** | The events picked when Teams was [installed](https://docs.orbits.africa/team/integrations#microsoft-teams) | | **Webhooks** | The events picked when the [webhook](https://docs.orbits.africa/team/integrations#webhooks) was added | | **The bell** | Always on, for everyone in the team | [Alerts](https://docs.orbits.africa/observe/alerts) are separate: each alert rule says itself whether it emails the team or calls the alert webhook. ## The team's switches Go to **Team › Settings › Notifications**. Each event has an **Email** switch and a **Slack** switch. Owners and admins change them; changes save as you make them. | Event | When | Email by default | Slack by default | | --- | --- | --- | --- | | **A deploy fails** | A production or preview build fails | On | On | | **A production deploy goes live** | After every promote or push to the production branch, once it serves the site | Off | On | | **A domain or certificate needs attention** | A domain's DNS stops pointing at Orbits, a certificate can't be issued, or one within 14 days of expiring hasn't renewed | On | On | | **Someone joins the team** | Including people who accepted an invite. Nobody is told about themselves joining | On | Off | | **Weekly summary** | Mondays at 9:00, Lagos time | On | Off | Slack switches only matter once Slack is connected. A failed deploy's email says why it failed and on which branch. A domain that's still not set up an hour after it was added also gets its own "DNS needed" email, to whoever added it; the domain switch turns that off too. ### Who gets the emails Team email goes to **everyone who can deploy**: owners, admins and members. Viewers don't get team email. The "DNS needed" email goes only to the person who added the domain. There is no per-person opt-out yet: the switches are for the whole team. ## The weekly summary Every Monday at 9:00 Lagos time, for the past Monday to Sunday across all the team's projects: - **Visitors** per day and **top pages**, from [Analytics](https://docs.orbits.africa/observe/analytics); - **Deploys** and the **average build time**; - **Mobile Web Vitals** from the busiest project with [Speed Insights](https://docs.orbits.africa/observe/speed-insights). Analytics and Speed Insights figures appear only for projects that have them, which needs Pro. When the Slack switch is on, a short version (visitors, deploys, build time) is posted in the channel picked for "promoted to production", or another channel the Slack page has. Microsoft Teams and webhooks don't get the weekly summary. ## The bell The bell in the top bar shows what's worth a look in the current team, newest first: | Notification | | | --- | --- | | A deploy failed | With the reason and the branch, such as "Missing module 'mdsvex' · main" | | A domain is live | It has its certificate and serves over HTTPS | | A domain stopped pointing at Orbits | Check its DNS record | | A certificate couldn't be issued, or isn't renewing | | | Someone joined | With who invited them, such as "Invited by Tunde". Not your own joining | | An alert fired | | A dot on the bell means there are notifications you haven't read, and the list says how many are new. Opening one takes you to its page. **Mark all as read** clears them, for you only; everyone has their own read state. The bell goes back 30 days, and no further than when you joined the team. Everything else that happens is on the [activity feed](https://docs.orbits.africa/team/activity). ## From the API | Call | | | --- | --- | | `GET /v1/teams/{team}` | The team, with `notifications`: each event's `email` and `slack` switch | | `PATCH /v1/teams/{team}` | Change switches. Send only what changes: `{"notifications": {"deploy.live": {"email": true}}}` | | `GET /v1/teams/{team}/notifications` | The bell's list, with `unread_count`; `unread=true` for unread only | | `POST /v1/teams/{team}/notifications` | Mark read: `{"ids": [...]}` or `{"all": true}` | The events are named `deploy.failed`, `deploy.live`, `domain.attention`, `member.joined` and `weekly`. See [API › Teams](https://docs.orbits.africa/api/teams). --- # Integrations Source: https://docs.orbits.africa/team/integrations Post deploy, domain and member events to Slack or a Microsoft Teams channel, or send them to your own endpoint as signed webhooks. One place, Team › Integrations, for every tool your team connects. ## The Integrations page **Team › Integrations** has two tabs: - **Browse**: what you can connect, each with **Install** or **Installed**. - **Installed**: what the team has connected, with a one-line summary ("Posts to #deploys and #alerts"), its scope (**All projects** or the ones picked), when it was installed and by whom. Anyone in the team can see the page. Owners and admins install, change and remove integrations. [API tokens](https://docs.orbits.africa/team/api-tokens) can list integrations but can't change them. This page covers Slack, Microsoft Teams and webhooks. GitHub, GitLab and Bitbucket, where Orbits pulls your code from, are on [Git providers](https://docs.orbits.africa/deploy/git). ## Slack ### Install 1. On **Browse**, pick **Slack** and press **Install**. 2. Slack asks you to add Orbits to a workspace. Orbits asks to post messages, to post in public channels without being invited, and to list channels for the picker. It can't read your messages. 3. Approve, and you're back on Orbits with Slack connected. On a first install, each event is pointed at a starting channel if the workspace has it: failed deploys and domain problems at `#alerts`, production deploys at `#deploys`, new members at `#general`, otherwise `#general`. ### Choose channels and projects Slack's page in Integrations says **where** each event goes: | Event | Channel | | --- | --- | | **Deploy failed** | Any public channel, or none | | **Promoted to production** | | | **Domain verified or misconfigured** | | | **New member joined** | | and **which projects send events**: all, or the ones you pick. Changes save on their own. Only public, unarchived channels are offered. **Team › Settings › Notifications** says **whether** each event goes to Slack, with its Slack switch (see [notifications](https://docs.orbits.africa/team/notifications)). An event is posted when its Slack switch is on, it has a channel here, and its project is in scope. The [weekly summary](https://docs.orbits.africa/team/notifications#the-weekly-summary) is posted too when its Slack switch is on. ### When it needs attention If someone removes the Orbits app from the Slack workspace, the integration shows that it needs attention and Orbits stops posting. Press **Reconnect** and approve again: your channels and projects are kept. **Uninstall** stops posting and revokes Orbits' access in Slack. Messages still waiting to go are dropped. ## Microsoft Teams Teams connects through a **workflow** in the channel, not a Microsoft sign-in. There is no app to approve and no tenant admin to ask; messages show as coming from Workflows. ### Install 1. In Microsoft Teams, open the channel and add the workflow **Post to a channel when a webhook request is received**. 2. Copy the workflow's URL. 3. In Orbits, on **Browse**, pick **Microsoft Teams** and press **Install**. 4. Paste the URL and pick which events to post: a deploy failing, a production deploy going live, a domain verified or misconfigured, someone joining. Pick at least one. 5. Save. Only workflow URLs on `*.logic.azure.com` or `*.api.powerplatform.com` are accepted. Orbits keeps the URL encrypted and afterwards shows only its host: the URL works like a password, so anyone who has it can post to your channel. Orbits posts a card for each event, with what happened, the facts and a button to open it in Orbits. Teams' page shows who installed it and how many messages went this month. To change the events or the channel, uninstall and install again. **Uninstall** makes Orbits forget the URL and stop posting; the workflow stays in Teams until you remove it there. ## Webhooks Send events to your own endpoint, signed so you can check they came from Orbits. A team has **one** webhook. ### Add one 1. On **Browse**, pick **Webhooks** and press **Install**. 2. Enter the endpoint's address: `https`, on the public internet. 3. Pick the **events** to send (at least one) and the **projects** that send them. 4. Copy the **signing secret** the dialog shows, `whsec_` and a string of letters and digits, into your receiver. If you add the webhook through the API without a secret, Orbits makes one and returns it in that answer only. 5. Save. To change the address, events or projects, remove the webhook and add it again. **Remove** stops sending; deliveries still waiting are dropped. The page shows the secret's last four characters and how many deliveries went this month. ### Events | Event | Sent when | `data` holds | | --- | --- | --- | | `deployment.created` | A deploy is queued | `deployment` | | `deployment.ready` | Any deploy is ready, production or preview | `deployment` | | `deployment.failed` | A deploy fails | `deployment` | | `domain.updated` | A domain changes, including when it's verified or stops pointing at Orbits | `domain` | | `member.joined` | Someone joins the team (not the person who created it) | `member` | | `project.created` | A project is created | `project` | `deployment` is the deployment as the API returns it from `GET /v1/teams/{team}/projects/{project}/deployments/{id}`. ### What a request looks like ```http POST /orbits-hook HTTP/1.1 Content-Type: application/json User-Agent: Orbits-Webhooks/1 X-Orbits-Event: deployment.ready X-Delivery-Id: idl_… Orbits-Signature: sha256=5d41402abc4b2a76b9719d911017c592… X-Signature-256: sha256=5d41402abc4b2a76b9719d911017c592… ``` ```json title="Body" { "id": "evt_…", "type": "deployment.ready", "created_at": "2026-11-02T08:30:00Z", "team": { "id": "team_…", "slug": "acme" }, "data": { "deployment": { "id": "dpl_…" } }, "delivery_id": "idl_…" } ``` | Header | | | --- | --- | | `X-Orbits-Event` | The event's type | | `X-Delivery-Id` | The same on every retry of one delivery (it's also in the body), so you can drop a repeat | | `Orbits-Signature` | `sha256=` and the hex HMAC-SHA256 of the raw body, keyed with the whole secret, `whsec_` included | | `X-Signature-256` | The same value, as [alert webhooks](https://docs.orbits.africa/observe/alerts#what-the-webhook-receives) send it, so one receiver can check both | Answer with any `2xx` within 10 seconds. Anything else, or no answer, is tried again: five tries in all, over about half an hour. Redirects aren't followed, and addresses that aren't on the public internet are refused. Events more than an hour old aren't sent. ### Verify the signature Work out the HMAC over the **raw bytes** of the body, exactly as they arrived, before any JSON parsing, and compare it in constant time. ::::tabs :::tab[Node] ```ts title="verify.ts" import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyOrbits(rawBody: Buffer, header: string | undefined, secret: string): boolean { if (!header?.startsWith("sha256=")) return false; const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"); const a = Buffer.from(header); const b = Buffer.from(expected); return a.length === b.length && timingSafeEqual(a, b); } ``` With Express, take the body raw on the webhook's route: ```ts title="server.ts" import express from "express"; import { verifyOrbits } from "./verify"; const app = express(); const seen = new Set(); app.post("/orbits-hook", express.raw({ type: "application/json" }), (req, res) => { if (!verifyOrbits(req.body, req.get("Orbits-Signature"), process.env.WEBHOOK_SECRET!)) { return res.status(401).end(); } const delivery = req.get("X-Delivery-Id")!; if (!seen.has(delivery)) { seen.add(delivery); const event = JSON.parse(req.body.toString("utf8")); console.log(event.type, event.data); } res.status(204).end(); }); app.listen(3000); ``` ::: :::tab[Python] ```python title="verify.py" import hashlib import hmac def verify_orbits(raw_body: bytes, header: str | None, secret: str) -> bool: if not header or not header.startswith("sha256="): return False expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(header, expected) ``` With Flask: ```python title="app.py" import json import os from flask import Flask, request from verify import verify_orbits app = Flask(__name__) @app.post("/orbits-hook") def orbits_hook(): if not verify_orbits(request.get_data(), request.headers.get("Orbits-Signature"), os.environ["WEBHOOK_SECRET"]): return "", 401 event = json.loads(request.get_data()) print(event["type"], event["data"]) return "", 204 ``` ::: :::: Keep a record of the `X-Delivery-Id` values you've handled (in a database, not memory, in production), so a retry of something you already processed is dropped. ## Not here yet A test button and a delivery log for Slack, Teams and webhooks aren't available yet. To test a receiver, use the [alert webhook](https://docs.orbits.africa/observe/alerts#the-team-webhook)'s **Send test event**, which is signed the same way. ## From the API | Call | Who | | --- | --- | | `GET /v1/teams/{team}/integrations` | Any member. Everything, with what's installed | | `GET`, `PATCH`, `DELETE .../integrations/slack` | `GET` any member; changes owners and admins | | `POST .../integrations/slack/install` | Owners and admins. Slack's "add to workspace" address | | `GET .../integrations/slack/channels` | Owners and admins. The channel picker | | `GET`, `POST`, `DELETE .../integrations/teams` | `POST` takes `url` and `alerts` | | `GET`, `POST`, `DELETE .../integrations/webhooks` | `POST` takes `url`, `events`, optionally `secret` and `scope` | See [API › Integrations](https://docs.orbits.africa/api/integrations). --- # Two-factor and team security Source: https://docs.orbits.africa/team/security Protect your account with an authenticator app and ten one-time recovery codes. Owners and admins can require two-factor for the whole team, limit how members sign in, sign them out after a set time and choose who can invite. ## Two-factor for your account Two-factor means a stolen password or sign-in link isn't enough: Orbits also asks for a code from an authenticator app on your phone when you sign in. It's set per person, on your account, and covers every team you're in. ### Turn it on 1. Go to **Account** and find the **Two-factor** card. It says **Two-factor is off.** 2. Press **Turn on two-factor**. 3. Scan the code with an authenticator app (1Password, Authy, Google Authenticator or any other that does time-based codes), or type the key shown under it. 4. Enter the 6-digit code the app shows. 5. Two-factor is on, and Orbits shows your **recovery codes**. :::warning[Save your recovery codes now] You get **ten recovery codes**, like `k7pm-x2qa`. They're shown **once**: Orbits keeps only a hash of each, so it can't show them again. Copy them somewhere other than your phone. Each code works once, and gets you in if you lose your phone. ::: Starting again before you've entered a code just gives you a new key; nothing is on until the first code is accepted. ### Signing in with two-factor After the sign-in link, or GitHub, GitLab or Bitbucket, Orbits asks for a code: - A code from the app is 6 digits and changes every 30 seconds. Each code works once. - Or enter a **recovery code**. Case, spaces and the dash don't matter. A recovery code works once, ever. - You have 10 minutes to enter it before you need to sign in again. - After **five wrong codes in a row**, codes are refused for 15 minutes. The message says how long is left. ### New recovery codes, and turning it off The Two-factor card shows how many recovery codes you have left. - **Generate new recovery codes** replaces them with ten new ones, shown once. Your old codes stop working. It asks for a current code from your app (or a recovery code). - **Turn off two-factor** also asks for a current code or a recovery code, so someone who only has your session can't turn it off. Your recovery codes go with it. If a team you're in requires two-factor, turning it off locks you out of that team until you turn it on again. ## Team security rules Owners and admins set these on **Team › Settings › Security**. They apply in this team only: a member who doesn't meet one is refused on this team, with a sentence saying why, while their other teams keep working. ### Require two-factor for everyone Turn on **Require two-factor for everyone** and every member must have two-factor on to use the team. - You need two-factor on your own account first, so you can't lock yourself out. - Members without it can still sign in, but this team's pages and its API answer with "This team requires two-factor authentication" until they turn it on. Members without it are asked to turn it on the next time they sign in. They can still leave the team. - Their [API tokens](https://docs.orbits.africa/team/api-tokens) are refused too, since a token acts as the person who made it. - The Security card lists the members who don't have it, and the **Two-factor** column on **Team › Members** shows everyone's status as of their last visit. ### Sign-in methods Choose how members may have signed in: **Email link**, **GitHub**, **GitLab** and **Bitbucket**. A member whose session started with a method you've switched off is refused on this team ("This team only allows signing in with GitHub…") until they sign out and in again with one that's allowed. You must keep at least one method, and you can't switch off the one you signed in with yourself. Sessions started before Orbits recorded how people signed in count as an unknown method, so with a limit in place those members are asked to sign in again once. These rules are for people signed in to the web app. API tokens aren't affected by them. ### Sign members out after **1 day**, **7 days** or **30 days**. A member whose session started longer ago than that is refused on this team ("…sign in again every 7 days…") until they sign in again. Every session ends after 30 days anyway. API tokens aren't affected. ### Who can invite people | Setting | Who can invite | | --- | --- | | **Owners only** | Owners and admins (the default) | | **Owners and members** | Members too, as a member or viewer only | Viewers never can, and only owners invite owners and admins. See [inviting people](https://docs.orbits.africa/team/teams-and-roles#invite-people). API tokens can't change any of these rules. ## Other protections - **Preview protection**: password-protect a project's previews, or keep them to signed-in team members, from the project's settings. See [previews](https://docs.orbits.africa/deploy/previews). - **Sensitive environment variables** are write-only: nobody can read them back. See [environment variables](https://docs.orbits.africa/deploy/environment-variables). - How Orbits keeps your data and code safe is on [security and privacy](https://docs.orbits.africa/help/security-and-privacy). ## From the API | Call | | | --- | --- | | `GET /v1/me/two-factor` | Whether it's on, since when, and recovery codes left | | `POST /v1/me/two-factor`, then `POST /v1/me/two-factor/confirm` with `code` | Turn it on. The confirm answer carries the recovery codes, once | | `POST /v1/me/two-factor/recovery-codes` with `code` | New recovery codes | | `POST /v1/me/two-factor/disable` with `code` | Turn it off | | `PATCH /v1/teams/{team}` | `require_two_factor`, `sign_in_methods` (`email`, `github`, `gitlab`, `bitbucket`), `session_max_age_days`, `inviters` (`owners` or `members`) | See [API › Authentication](https://docs.orbits.africa/api/authentication) and [API › Teams](https://docs.orbits.africa/api/teams). --- # Activity Source: https://docs.orbits.africa/team/activity Who changed what across the team, one sentence a line, kept for 90 days. Filter it by person, project and kind, search it, and export it as CSV. ## The activity feed **Team › Activity** is the team's record of what happened: who deployed, who changed a variable, who joined, which domain went live. Each line is one sentence, newest first, like: - *Ada started a preview of checkout* - *storefront failed to deploy on main* - *Tunde revealed DATABASE_URL* - *shop.example.ng is live with HTTPS* - *Checkout errors fired: 8% errors over 5 minutes* A failed build's line is shown in red. Lines that are about a deployment link to it. Every project has its own **Activity** tab too, with just that project's lines. :::note[Kept for 90 days] Lines are kept for 90 days, the page's longest range, then deleted. Export them as CSV if you need them for longer. ::: ## What's in it | Kind | Lines for | | --- | --- | | **Deployments** | A preview started, production deployed, promoted or rolled back, a build failed | | **Variables** | Environment variables added, updated, removed, restored, revealed or pulled. Lines name the keys, never the values | | **Projects** | Created, renamed, settings changed, paused or resumed, deleted, moved in from another team | | **Members** | Someone joined (and who invited them), left, or had their role changed | | **Team** | The team created, renamed or its settings changed; Pro upgraded, cancelled, resumed, a payment failed or the team went back to Free; an API token created or revoked | | **Integrations** | A Git provider connected or disconnected | | **Domains** | A domain added, changed, redirected or removed; live with HTTPS; stopped pointing at Orbits; a certificate that couldn't be issued or is about to expire | Alerts firing and resolving are in the feed as well. Some things aren't news and aren't written: builds starting or being cancelled, and invites being sent. Each line names who did it: a member, a commit's author for a push, or Orbits itself for something that happened on its own, like a domain going live. Lines read as they did at the time. If a project or person is renamed later, older lines keep the old name, and a deleted project's lines stay. Lines appear a moment after what they describe. ## Filter and search | Control | | | --- | --- | | **Search activity** | Matches the sentence, the person's name or the project's name, in any case | | **Person** | Anyone who appears in the feed. **Anyone** shows all | | **Project** | Any project the feed mentions | | Type | One kind from the table above, or several | **Export CSV** downloads the lines that match your filters. Any member of the team can read the feed, viewers included. ## Activity, notifications and the bell The feed has everything. The [bell](https://docs.orbits.africa/team/notifications#the-bell) shows the few lines worth a nudge (a failed deploy, a domain going live or failing, someone joining, an alert firing) and remembers what you've read. Emails, Slack and webhooks are set up in [notifications](https://docs.orbits.africa/team/notifications) and [integrations](https://docs.orbits.africa/team/integrations). ## From the CLI and the API ```console $ orbits activity ``` `GET /v1/teams/{team}/activity` returns a page of lines with: | Parameter | | | --- | --- | | `q` | Search, up to 200 characters | | `actor` | A person's id, from the answer's `people` | | `project` | A project's id or slug | | `type` | `deployments`, `variables`, `projects`, `members`, `team`, `integrations` or `domains`; several separated by commas | | `since` | The oldest line to return. Defaults to 7 days ago, and can go back 90 days | | `limit`, `cursor` | Up to 100 a page; send `next_cursor` back as `cursor` for more | ```json title="One line" { "id": "act_…", "type": "deployment.failed", "category": "deployments", "actor": { "kind": "git", "user_id": null, "name": "Ada Obi" }, "summary": "storefront failed to deploy on main", "project": { "id": "prj_…", "slug": "storefront", "name": "storefront" }, "deployment_id": "dpl_…", "failed": true, "created_at": "2026-11-10T09:14:03Z" } ``` `total` counts matching lines up to 10,000. See [API › Usage and activity](https://docs.orbits.africa/api/usage-and-activity). --- # Plans Source: https://docs.orbits.africa/billing/plans Orbits has two plans per team. Free hosts unlimited projects. Pro, at $5 a month paid in Naira, adds server functions, Analytics and Speed Insights. What each includes, what happens when Pro ends, and the plan_required error. ## Free and Pro A plan belongs to a **team**, not a person: every project in the team gets what the team's plan includes. Owners manage the plan; everyone in the team can see which plan it's on. | | Free | Pro | | --- | --- | --- | | Price | Nothing | **$5 a month**, charged in Naira | | Projects | Unlimited | Unlimited | | Static sites, Node apps, workers | Yes | Yes | | Next.js, SvelteKit, Nuxt, Remix and other server-rendered apps | Yes, run as apps | Yes, as server functions | | The `function` workload (server functions) | No | Yes | | [Analytics](https://docs.orbits.africa/observe/analytics) | No | Yes | | [Speed Insights](https://docs.orbits.africa/observe/speed-insights) | No | Yes | | Sandboxes | No | Yes, once they're available | | Previews, custom domains, Orbits DNS, logs, observability, alerts, flags, workflows | Yes | Yes | Pro is priced in US dollars and charged in Naira through Flutterwave. See [paying for Pro](https://docs.orbits.africa/billing/paying). :::note[Free apps stay on] Free apps run all the time, like Pro's. Orbits doesn't put idle apps to sleep. ::: ### Server-rendered apps on Free On Free, a project whose framework would run as a server function (Next.js, SvelteKit, Nuxt, Remix and the like) is created as an ordinary **app** instead. It builds and serves the same way. Asking for the `function` workload outright on Free is refused with `plan_required`. ### Previews on Pro On Pro, a project serves at most **3 ready previews at a time**, the three newest; when a fourth is ready, the oldest stops being served. Redeploying its branch builds it again. Production is never affected or counted. See [previews](https://docs.orbits.africa/deploy/previews). ### Sandboxes Sandboxes, on-demand development machines for a project, are part of Pro but aren't available yet. ## Upgrading An owner upgrades the team from its billing page. Pro starts as soon as the payment is confirmed, and every Pro feature is available at once. See [paying for Pro](https://docs.orbits.africa/billing/paying). ## When a feature needs Pro: `402 plan_required` Anything Free doesn't include is refused with **`402 Payment Required`**, in the web app as an upgrade prompt and in the API as: ```json { "title": "Payment Required", "status": 402, "detail": "Analytics are on the Pro plan.", "code": "plan_required", "required_plan": "pro", "feature": "analytics", "request_id": "…" } ``` `feature` names what's missing: `analytics`, `speed_insights`, `functions` or `sandboxes`. You get it for: - turning **Analytics** or **Speed Insights** on (turning them off always works); - creating a project with the **`function`** workload, or deploying, redeploying or promoting a project that runs as one; - creating or starting a **sandbox**. Reading a Pro feature's page on Free shows it as locked rather than failing. See [API › Errors](https://docs.orbits.africa/api/errors). ## When Pro ends Pro ends when an owner [cancels](https://docs.orbits.africa/billing/paying#cancel-and-resume) it (at the end of the month already paid) or when a renewal isn't paid by the end of the 7-day grace period. The team goes back to Free, and Orbits **stops new use but keeps your data**: | | What happens | | --- | --- | | Analytics and Speed Insights | Collection stops. What was collected, and the switches, are kept but hidden | | Projects that run as server functions | Keep running and serving. They can't be deployed, redeployed or promoted on Free; a build started by a push fails with "Pro plan required" | | Sandboxes | Stop, and can't be started | | Everything else | Unchanged | Nothing is deleted. Pay for Pro again and everything comes back at once: Analytics and Speed Insights start collecting again, and server-function projects can deploy. ## Deleting a team on Pro Deleting a team ends its Pro plan straight away, **with no refund**. Nothing is charged again and the saved card is forgotten. Paid invoices are kept as the record of the payment. See [deleting a team](https://docs.orbits.africa/team/teams-and-roles#delete-a-team). ## From the API `GET /v1/plans` lists the plans and their prices, with no sign-in needed. Each plan has its `id` (`free` or `pro`), `name`, `usd_cents` (`500` for Pro), `ngn` and `features` (`unlimited_projects`, `functions`, `sandboxes`, `analytics`, `speed_insights`). The answer's `rate` is the dollar-to-Naira rate in use. `ngn` is Pro's Naira price at today's rate, rounded up to a whole ₦100; it's `null` while Pro can't be bought. `GET /v1/teams/{team}/billing` says which plan the team is on and `entitlements`, what it may use right now. See [API › Billing](https://docs.orbits.africa/api/billing). --- # Paying for Pro Source: https://docs.orbits.africa/billing/paying Pro is $5 a month, charged in Naira through Flutterwave's hosted page by card or bank transfer. How the Naira price is set, how monthly renewal and the 7-day grace period work, cancelling and resuming, invoices and the emails owners get. ## Who pays Only the team's **owners** can pay for Pro, cancel or resume it, and see invoices and the card on file. Admins and members see which plan the team is on. Paying needs an owner signed in to the web app: [API tokens](https://docs.orbits.africa/team/api-tokens) can read the billing state but never change it. ## The price in Naira Pro is **$5 a month**. You pay in Naira: - The Naira price is the dollar price at a **rate Orbits sets**, **rounded up to a whole ₦100**. The billing page and the upgrade prompt show it. - When you start paying, that amount is **locked on the invoice**, and it's exactly what's charged, even if the rate changes before you finish. - If the price changes between the moment you saw it and the moment you press pay, Orbits stops and shows you the new price instead of charging something you didn't see. ## Pay for Pro 1. On the team's billing page, choose to upgrade to Pro. The Naira price is shown. 2. You're sent to **Flutterwave's hosted payment page**. Pay by **card** or **bank transfer**. 3. Flutterwave sends you back to Orbits, which checks the payment. 4. When Flutterwave confirms it, the team is on Pro. Everything Pro includes works at once. A card payment usually confirms in seconds. A **bank transfer** can take longer to arrive: the page says the payment is pending, and the team becomes Pro as soon as the money lands, even if you closed the page. Nothing is granted until Flutterwave confirms the payment for the full amount on the invoice, in Naira. If a payment fails or isn't for the right amount, nothing changes and you can try again, which starts a new payment. :::note[Orbits never sees your card] Card and bank details are typed on Flutterwave's page only. Orbits never sees or stores a card number. It keeps only the card's brand, last four digits and expiry, and a token from Flutterwave that lets it charge the same card for renewals. ::: ## Your month A paid month runs from the day you pay to the same day of the next month (Lagos time). Short months are clamped: a month bought on 31 January runs to 28 February, then to 31 March. Paying again while Pro is still running buys the month after the current one. ## Renewal Pro renews by itself each month. 1. **3 days before the month ends**, Orbits makes the renewal invoice, at that day's rate. Its amount doesn't change after that. Owners get an email saying the renewal is coming and whether the card will be charged or they need to pay. 2. **When the month ends**, the saved card is charged. 3. If that fails, it's tried again **1, 3 and 5 days** after the month ended. Each try has its own reference, and a charge is never repeated while an earlier one is still being processed, so a card is never charged twice for one month. ### The grace period If the card fails, Pro keeps working for a **7-day grace period** from the end of the month, while the tries above run. Owners get a "payment failed" email on the first failure and a reminder the day before grace ends. If nothing is paid by the end of grace, the team goes back to Free (see [when Pro ends](https://docs.orbits.africa/billing/plans#when-pro-ends)). Nothing is deleted, and paying again brings everything back. ### If you paid by bank transfer A bank transfer leaves no card to charge, so **teams that pay by transfer renew by paying on the billing page**. The owners are told when the renewal is due, and Pro runs on through the grace period while they pay. The same goes for a card that can't be charged without your approval each time. ### Paying a renewal early or late The billing page can pay an open renewal at any time, at its locked price. Paying early renews early: the new month starts from the end of the one already paid. Paying during grace starts the new month from the day you pay. Paying a renewal by card makes that card the one on file. Changing the card any other way isn't available yet. ## Cancel and resume **Cancel** stops Pro renewing. The team keeps Pro until the end of the month already paid, then goes back to Free. The renewal invoice is voided and nothing more is charged. **Resume**, before that month ends, undoes the cancellation: Pro renews again as before. After the month has ended, the plan is gone; upgrade again to start a new one. Cancelling doesn't delete anything. A plan Orbits granted itself can't be cancelled. ## Invoices and receipts The billing page lists the team's **invoices**, newest first: payments made for Pro. Payments started but never finished aren't listed. Each invoice shows: | | | | --- | --- | | Kind | A first purchase, a renewal, or a payment made by hand | | Amount | The dollar price, the Naira amount charged and the rate it was converted at | | Period | The month it paid for | | How it was paid | Card (with its brand and last four digits) or bank transfer | | Reference, paid on | The payment's reference and date | Open one to see it as a **receipt**: who paid, for which team, what for, and the card. There's no PDF; the receipt is a page you can print. Invoices are kept for good, even if the team is deleted, because they're the record of money taken. ## Emails Owners get, at most once for each invoice: | Email | When | | --- | --- | | **Receipt** | A payment went through | | **Renewal coming up** | 3 days before the month ends, saying whether the card will be charged or you need to pay | | **Payment failed** | The first time a renewal charge fails | | **Grace ending** | 1 day before the grace period ends | | **Back on Free** | The team went back to Free | Owners also see a notice about the plan while a renewal is coming up, a payment has failed, Pro is set to end, or for 30 days after the team went back to Free. Plan changes, cancellations, resumes and failed payments are lines in the team's [activity feed](https://docs.orbits.africa/team/activity). ## From the API Owners only, signed in: | Call | | | --- | --- | | `GET /v1/teams/{team}/billing` | The plan, `status` (`free`, `active` or `past_due` in grace), the current period, the next charge, the card (owners) and the notice. Any member can read it | | `POST .../billing/checkout` | Start paying. Body: `expected_ngn` (the price you were shown) and `return_path`. Answers with Flutterwave's page. `409 price_changed` if the price moved | | `POST .../billing/verify` | With `tx_ref`, after returning from Flutterwave: `paid`, `pending` or `failed` | | `POST .../billing/cancel`, `.../resume` | Cancel at the end of the month, or undo it | | `GET .../billing/invoices`, `.../invoices/{invoice}` | Invoices, and one as a receipt | A `503 billing_unavailable` means Pro can't be bought or checked right now; try again shortly. See [API › Billing](https://docs.orbits.africa/api/billing). --- # Usage Source: https://docs.orbits.africa/billing/usage What your team and each project used this month, day by day. Requests, bandwidth, build minutes, function runs, deployments and log lines, compared with the month before, with a CSV export. ## The Usage pages **Team › Usage** shows what the whole team used in a month, day by day and project by project. Each project has its own **Usage** tab with its row of the same figures, split by environment. Any member of the team can see both. Pick a month from the period filter: every month from the team's first deployment to now. Days are Lagos days, and today's figures are as of when you opened the page. ## What's measured | Measure | What it counts | | --- | --- | | **Requests** | Requests Orbits' edge sent to the team's deployments, production and previews | | **Bandwidth** | Bytes the edge sent back in answers, headers included | | **Build minutes** | Each build from start to finish, failed builds included, by the day it was created | | **Function runs** | Requests to projects that run as server functions. Each is also counted in Requests | | **Deployments** | Deployments created, by day | | Log lines | Lines in the projects' [runtime logs](https://docs.orbits.africa/observe/runtime-logs) | Bandwidth is counted from when Orbits started recording it, so requests before then count as 0 bytes. Function runs count a call to the function for each request. Server functions run as one long-lived server for now, so this is a count of requests, not of separate starts. ### Compared with last month Each figure is compared with the same days of the month before ("+18% on September"). A team with no deployments before this month has nothing to compare with. ### By project **By project** lists every project the team has, sorted by requests, each with its month's totals and its days. A project's own Usage tab adds **By environment** (production, preview and development, where there's usage) and how many branches had a preview deployment this month. **Deleted projects** keep counting in the team's totals, in a row of their own, after the project is gone. ### When figures are missing Requests, bandwidth, function runs and log lines come from the runtime logs. If those can't be read for a moment, the page shows them as unavailable rather than as zero. Builds and deployments still count. Daily usage is kept for 400 days. The runtime logs themselves are kept for 7 days. ## Usage and your plan Orbits doesn't charge by usage: [Free and Pro](https://docs.orbits.africa/billing/plans) are flat. The Usage pages are there so you can see what your projects do. The plan's limits are on [limits](https://docs.orbits.africa/billing/limits). ## Export **Team › Usage** and a project's Usage tab can be downloaded as CSV for the month shown. ## The team overview The team's home page shows a short version over the last 24 hours, 7 days or 30 days: deployments (against the range before), the average build time of those that went ready, requests (and this month's so far, since midnight on the 1st in Lagos), and projects whose latest deployment failed. ## From the CLI and the API ```console $ orbits usage $ orbits usage --month 2026-10 ``` `GET /v1/teams/{team}/usage?month=2026-10` returns a month (this month if you leave `month` out; a month still to come is `422`): | Field | | | --- | --- | | `totals`, `previous` | The month's `requests`, `bandwidth_bytes`, `build_minutes` (one decimal place), `function_runs`, `deployments` and `log_lines`, and the same days of the month before (or `null`) | | `daily` | Each day's totals | | `by_project` | Each project's totals, days, `by_environment` and `preview_branches`, most requests first | | `deleted_projects` | Projects deleted since, counted in `totals` only | | `months` | Every month from the first deployment, newest first | | `logs_available` | `false` while the log figures can't be read; show them as unavailable | `GET /v1/teams/{team}/overview?range=7d` is the overview. See [API › Usage and activity](https://docs.orbits.africa/api/usage-and-activity). --- # Limits Source: https://docs.orbits.africa/billing/limits Every fixed limit in Orbits in one place. Upload sizes, how long logs and activity are kept, API rate limits, token and variable counts, and the limits of alerts, flags, workflows and Analytics. These are the limits Orbits applies today, for every plan unless a row says otherwise. What each plan includes is on [plans](https://docs.orbits.africa/billing/plans). ## How long things are kept | What | Kept for | | --- | --- | | [Runtime logs](https://docs.orbits.africa/observe/runtime-logs) | 7 days | | [Analytics](https://docs.orbits.africa/observe/analytics) and [Speed Insights](https://docs.orbits.africa/observe/speed-insights) data | 90 days (the pages show up to 30 days) | | [Activity feed](https://docs.orbits.africa/team/activity) | 90 days | | [Alert](https://docs.orbits.africa/observe/alerts) history | 90 days | | The [bell](https://docs.orbits.africa/team/notifications#the-bell) | 30 days, and no further back than when you joined | | Daily [usage](https://docs.orbits.africa/billing/usage) | 400 days | | Flags' "Seen in the last 24 hours" | Kept by the hour for 2 days | | A deleted environment variable | 10 minutes, during which it can be restored | | Uploaded folders | The last 5 per project, so Redeploy can rebuild them | | Invoices | For good, even after the team is deleted | ## Deployments | | Limit | | --- | --- | | [Uploaded folder](https://docs.orbits.africa/getting-started/upload-a-folder) | 100 MB zipped; 500 MB and 20,000 files unpacked | | A build's log | 5,000 lines | | The ignored build step | 2 minutes; a run over that builds | | Live previews per project, on Pro | The 3 newest ready previews are served; the oldest stops first | | A branch's preview | Served while it was built in the last 14 days; redeploy the branch to bring it back | ## Environment variables | | Limit | | --- | --- | | Variables per project | 1,000 | | Variables in one request (or one import) | 500 | | One value | 32 KiB | See [environment variables](https://docs.orbits.africa/deploy/environment-variables). ## API | | Limit | | --- | --- | | A signed-in person | 1,200 requests a minute, bursts of 400 | | An API token | 300 requests a minute, bursts of 100, apart from its maker's | | A team, everyone and every token together | 6,000 requests a minute | | Sign-in and account routes, invite lookups | 300 a minute per address | | Asking for a sign-in email | 30 a minute per address; 5 in a row per email address, then one every 3 minutes | | A request body | 1 MiB | | A page of results | Usually up to 100 items; runtime logs up to 500 | Over a limit the API answers `429` with `Retry-After`. The flags and workflows packages' calls from your deployments aren't rate limited. Details: [rate limits](https://docs.orbits.africa/api/rate-limits). ## Team and account | | Limit | | --- | --- | | Team URL (slug) | 3 to 40 characters | | Active [API tokens](https://docs.orbits.africa/team/api-tokens) per team | 50 | | A token's name | 1 to 40 characters | | Token expiry | 30, 90 or 365 days, or never | | Invites in one go | 20 email addresses | | An invite | Expires after 7 days | | Team avatar | PNG, JPEG or WebP; the source image up to 10 MB, the cropped avatar up to 150 KB | | A session | 30 days at most; a team can make it 1 or 7 days | | Two-factor codes | After 5 wrong codes in a row, codes are refused for 15 minutes | | A two-factor sign-in | 10 minutes to enter the code | | Recovery codes | 10, each usable once | ## Previews | | Limit | | --- | --- | | A correct preview password | Remembered for 12 hours | | A team-only preview's sign-in link | 5 minutes | ## Alerts | | Limit | | --- | --- | | A rule's name | 60 characters, unique in the project | | Windows | 1, 5, 10 or 30 minutes | | Routes per rule | 10 | | Requests a window needs (`error-rate`, `p75`, `p99`) | 20 | | Resolving | 3 checks in a row back on the right side | | A notice | Tried up to 5 times over about 30 minutes; 10 seconds to answer | | Alert webhooks | 1 per team | ## Feature flags | | Limit | | --- | --- | | A flag's key | 48 characters: lowercase letters, digits and single dashes | | A description | 120 characters | | Rules | 20 per flag per environment | | Rollout | 1% to 100% | ## Workflows | | Limit | | --- | --- | | A step's result, a run's input, an event's data | 256 KB as JSON | | A step's time | 5 minutes | | Retries per step | Up to 10 (2 by default) | | Scheduled runs | One a minute per workflow | | Event names | Up to 100 characters | ## Analytics and Speed Insights | | Limit | | --- | --- | | Custom event properties | 20, flat | | Event names, keys and string values | 255 characters | | Lists on the pages | The top 10 | ## Integrations | | Limit | | --- | --- | | Webhooks | 1 per team | | A webhook delivery | 5 tries over about half an hour; 10 seconds to answer; events over an hour old aren't sent | | A webhook secret | `whsec_` and 12 to 64 letters, digits, `_` or `-` | | Slack channels offered | Public, unarchived channels, up to 1,000 | --- # Connect your AI app to Orbits Source: https://docs.orbits.africa/ai/connect-your-ai Let Claude, ChatGPT, Cursor, VS Code and other AI apps deploy and look after your Orbits projects, with one link and your approval. Paste one link into your AI app, approve it in the Orbits web app, and you can ask things like "why did my last deployment fail?" or "add shop.example.com to the storefront project". ```text https://mcp.theorbits.app/mcp ``` ## What MCP is MCP (the Model Context Protocol) is a standard way for an AI app to use outside tools. Orbits runs an MCP server at the link above. Your AI app connects to it and gets 48 [Orbits tools](https://docs.orbits.africa/ai/mcp-tools): list projects, read a build log, deploy a branch, roll back production, set an environment variable, add a domain, read runtime logs, check usage, and so on. Every tool calls the [Orbits API](https://docs.orbits.africa/api) with an API token that only this app holds, with the access you approved. Nothing else is shared. Anything that deletes something, changes what production serves, changes a domain or DNS record, or shows a secret value [asks you first](https://docs.orbits.africa/ai/mcp-tools#it-asks-before-it-changes-production-dns-or-deletes). ## How connecting works 1. Add the link to your AI app (the steps for each app are below). 2. The app opens your browser at the web app's **Connect** page. Sign in if you need to. 3. Choose the team, the access and when it expires, then press **Allow**. 4. Go back to your AI app. It is connected. You need to be an owner or admin of the team, because only they can create API tokens. If you aren't one in any team, the page says so. ### What the approval page asks - **Team.** If you own or administer more than one, pick the one this app may use. One connection works in one team. - **Access.** - **Full access**: deploy, change settings and domains. This is the default, unless the app asked only to read. - **Read only**: see projects, deployments and logs, and change nothing. Good for questions about status, errors and usage. - **Expires.** In 30 days, in 90 days or in a year. There is no "never" for an AI app. When it expires, the app asks you to approve it again. The page shows the app's name with the label **Not verified by Orbits**. Any app can call itself anything, so check the name and the address it will send you back to before you press **Allow**. [What the label means](https://docs.orbits.africa/ai/ai-apps-security#not-verified-by-orbits). Allowing creates an [API token](https://docs.orbits.africa/team/api-tokens) named after the app, like `Claude-Code-MCP`, in the team's **Settings › API tokens**. The page never shows it: it goes straight to the app. Revoke it there to disconnect the app. ## Set up your app The id in each tab is the one `orbits mcp install` takes. See [Use the CLI to set it up](#use-the-cli-to-set-it-up). ::::tabs :::tab[Claude] For claude.ai and Claude Desktop. Id: `claude`. 1. In Claude, open **Settings › Connectors** and choose **Add custom connector**. 2. Name it Orbits and paste `https://mcp.theorbits.app/mcp`. 3. Choose **Add**, then **Connect**, and allow access on the Orbits page that opens. ::: :::tab[ChatGPT] Id: `chatgpt`. 1. In ChatGPT, open **Settings › Connectors › Advanced** and turn on developer mode. 2. Choose **Create**, name it Orbits, and paste `https://mcp.theorbits.app/mcp`. 3. Choose **OAuth** for authentication, then **Create**, and allow access on the Orbits page that opens. ::: :::tab[Claude Code] Id: `claude-code`. ```console $ claude mcp add --transport http --scope user orbits https://mcp.theorbits.app/mcp ``` Then run `/mcp` inside Claude Code, choose **orbits** and sign in. Allow access on the Orbits page that opens. ::: :::tab[Cursor] Id: `cursor`. Add Orbits to `~/.cursor/mcp.json`: ```json title="~/.cursor/mcp.json" { "mcpServers": { "orbits": { "url": "https://mcp.theorbits.app/mcp" } } } ``` Then, in Cursor's MCP settings, choose **Connect** next to **orbits** and allow access on the Orbits page that opens. ::: :::tab[VS Code] Id: `vscode`. ```console $ code --add-mcp '{"name":"orbits","type":"http","url":"https://mcp.theorbits.app/mcp"}' ``` Start the **orbits** server when VS Code asks, and allow access on the Orbits page that opens. ::: :::tab[Windsurf] Id: `windsurf`. ```json title="~/.codeium/windsurf/mcp_config.json" { "mcpServers": { "orbits": { "serverUrl": "https://mcp.theorbits.app/mcp" } } } ``` Refresh Windsurf's MCP servers and allow access on the Orbits page that opens. ::: :::tab[Codex] Id: `codex`. ```toml title="~/.codex/config.toml" [mcp_servers.orbits] url = "https://mcp.theorbits.app/mcp" ``` Then sign in, and allow access on the Orbits page that opens: ```console $ codex mcp login orbits ``` ::: :::tab[Gemini CLI] Id: `gemini`. ```console $ gemini mcp add --scope user --transport http orbits https://mcp.theorbits.app/mcp ``` Or add it to `~/.gemini/settings.json` yourself. Gemini CLI finds the sign-in on its own: allow access on the Orbits page that opens. ```json title="~/.gemini/settings.json" { "mcpServers": { "orbits": { "httpUrl": "https://mcp.theorbits.app/mcp" } } } ``` ::: :::tab[Grok] Id: `grok`. For the xAI API. Grok doesn't sign in in a browser: it uses the xAI API's remote MCP tool, and sends an Orbits [API token](https://docs.orbits.africa/team/api-tokens) that you make under **Team › Settings › API tokens**. Make it **read** only unless Grok needs to make changes. Add Orbits to the tools of your xAI API request: ```json { "tools": [ { "type": "mcp", "server_url": "https://mcp.theorbits.app/mcp", "server_label": "orbits", "authorization": "Bearer orb_live_…" } ] } ``` Read the token from an environment variable or a secret store when you build the request. Never paste it into a prompt or your code. ::: :::: ### Apps that can't sign in Any app that can't sign in with OAuth can do what Grok does: send an API token from **Team › Settings › API tokens** as `Authorization: Bearer orb_live_…` to `https://mcp.theorbits.app/mcp`. A **read** token is a good start. ## Use the CLI to set it up The [Orbits CLI](https://docs.orbits.africa/cli) can write the config for you. It keeps every other server and setting in the app's file and saves the old file as `.bak`. For Claude Code and Gemini CLI it runs their own `mcp add` command (user scope) when they are installed. ```console $ orbits mcp install cursor $ orbits mcp install vscode --print # show the config, change nothing $ orbits mcp list-clients # the ids it knows $ orbits mcp status # the link, whether orbits-mcp is installed, and which apps have Orbits ``` For `claude` it prints the connector steps above. For `chatgpt` and `grok` it prints instructions only, since their setup lives in the app or your request. `--url` points it at another hosted server. ## Run it locally You can also run the MCP server on your own computer. It is a program called `orbits-mcp`. In this mode there is no browser approval: it uses a token you already have. Only the local server can [deploy a folder from your computer](https://docs.orbits.africa/ai/mcp-tools#deployments) (`deploy_folder`). Install it one of these ways: - Download an archive for macOS, Linux or Windows (amd64 or arm64) from the [releases page](https://github.com/The-Orbits/orbits-mcp/releases), and check it against `SHA256SUMS`: ```console $ shasum -a 256 -c SHA256SUMS --ignore-missing ``` - With Go 1.26 or later: ```console $ go install github.com/The-Orbits/orbits-mcp/cmd/orbits-mcp@latest ``` - With Docker (linux/amd64 and linux/arm64): ```console $ docker pull ghcr.io/the-orbits/orbits-mcp:latest ``` Then run it: ```console $ orbits-mcp stdio ``` It looks for a token in this order: 1. The `ORBITS_TOKEN` environment variable. 2. The token the [Orbits CLI](https://docs.orbits.africa/cli) stored when you ran `orbits login`, from your system's keychain or the CLI's `credentials.json`. Set `ORBITS_PROFILE` to pick a profile (and `ORBITS_CONFIG_DIR` if the CLI's settings are somewhere else). | Variable | What it does | | --- | --- | | `ORBITS_TOKEN` | The API token. Default: the Orbits CLI's sign-in | | `ORBITS_PROFILE` | The CLI profile to read. Default: the CLI's current one | | `ORBITS_API_URL` | The API. Default `https://api.theorbits.app/v1`, or the API the CLI profile signed in on. `--api-url` does the same | | `ORBITS_TEAM` | The default team's slug. Default: the CLI profile's team, else the token's own team. `--team` does the same | | `MCP_DISABLE_REVEAL` | `true` leaves out `reveal_env_var`, so no value can be read back | The server refuses a CLI config or credentials file that other users can write, and an API address that isn't `https` (or `localhost`). `orbits-mcp help` lists its commands. To point an app at the local server: ```console $ orbits mcp install claude-code --local ``` That runs `claude mcp add --scope user orbits -- stdio`. The CLI writes the full path, because apps opened from the dock or Start menu may not see your shell's `PATH`; write the full path too if you edit a config by hand (find it with `which orbits-mcp`). The same flag works for `claude` (it writes Claude Desktop's `claude_desktop_config.json`), `cursor`, `vscode`, `windsurf`, `codex` and `gemini`. ChatGPT and Grok can only use the hosted server. By hand, the config is the same for most apps: ```json title="claude_desktop_config.json" { "mcpServers": { "orbits": { "command": "orbits-mcp", "args": ["stdio"] } } } ``` Restart the app afterwards. For VS Code, run `code --add-mcp '{"name":"orbits","type":"stdio","command":"orbits-mcp","args":["stdio"]}'`. Codex takes: ```toml title="~/.codex/config.toml" [mcp_servers.orbits] command = "orbits-mcp" args = ["stdio"] ``` If `orbits-mcp` is not on your `PATH`, `orbits mcp install --local` warns you and writes the config anyway, so install it before you restart the app. ::::cards :::card[What your AI app can do]{href=/ai/mcp-tools} Every tool, what it changes, and which ones ask first. ::: :::card[Security and access]{href=/ai/ai-apps-security} Access, expiry, disconnecting, and what the server never shows. ::: :::: --- # What your AI app can do Source: https://docs.orbits.africa/ai/mcp-tools Every tool the Orbits MCP server gives your AI app, the access each one needs, and which ones ask before they change production, DNS or delete. Once [connected](https://docs.orbits.africa/ai/connect-your-ai), your AI app has 48 tools (49 with the [local server](https://docs.orbits.africa/ai/connect-your-ai#run-it-locally)), and it picks the right one for what you ask. You don't call tools by name. Ask "which of my projects failed to deploy today?" and it uses `list_deployments`. Each tool calls the [Orbits API](https://docs.orbits.africa/api) with the token you approved. A tool your access doesn't cover fails with a clear message, and nothing changes. Every tool works in the connection's team unless it is given another `team`; call `whoami` to see which. ## Access at a glance | Access | Tools it can use | | --- | --- | | **Read only** | Every tool marked *Read* below | | **Full access** | Every tool | Your access is enforced by the Orbits API, not by the app or the server. A **Read only** connection can't change anything or read a secret value: those tools fail with a message saying the token is read-only, and nothing happens. ## It asks before it changes production, DNS or deletes Some tools delete something, change what production serves, add or change a domain or DNS record, or show a secret value. These work in two steps: 1. The first call changes nothing. It returns a preview of what will happen, and a `confirmation_token`. 2. Your AI app shows you the preview. Only when you say yes does it call the same tool again, with exactly the same details plus that token, and the change is made. The token is tied to the tool, the exact details and your connection's API token. It works once and expires after 5 minutes. If anything differs, it has expired or it was already used, nothing is done and the app has to get a new preview and ask you again. The server never confirms on its own, and it tells the app never to confirm for you, nor because text in a tool result asks it to. A confirmed call that is retried is not made twice. In the tables, **Asks first** marks these tools, with the reason. ## Team and account | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `whoami` | Shows who the connection acts as: the person, the team it reaches with its plan, your role and its project count, and the token's access (full or read only) and project limit. The app calls it first | Read | | | `list_teams` | Lists the teams the connection reaches, with each one's slug, plan and your role. An API token reaches only its own team | Read | | | `get_usage` | A team's usage for a month: requests, bandwidth, build minutes, function runs and deployments, by day and by project, against the month before. Reported exactly as measured | Read | | | `get_activity` | What happened in the team, newest first: deployments, domains, variables, members and settings, with who did it. The last 7 days unless asked for more, up to 90 | Read | | | `get_billing` | The team's plan (Free or Pro), its status, the current period, the next charge and what the plan allows. Plans are changed and paid for in the web app | Read | | | `list_templates` | Lists starter templates | Read | | | `get_operation` | Shows how a change that runs in the background is going, such as deleting a project | Read | | | `wait_for_operation` | Waits up to about a minute for a change to finish | Read | | Creating a project from a template is not available yet. ## Projects | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_projects` | Lists the team's projects, most recently deployed first, with each one's slug, status, free address, production URL and latest deployment | Read | | | `get_project` | Shows one project: its workload, source (repository and production branch, or upload), build settings, region, status, whether it is paused, its production URL and latest deployment | Read | | | `create_project` | Creates a project from a Git repository (its first production deployment starts at once), or an upload project (nothing deploys until a folder is uploaded) | Full | | | `pause_project` | Pauses a project: its production site, previews and custom domains answer with Orbits' paused page until it is resumed. Its builds are kept | Full | Yes: production stops | | `resume_project` | Resumes a paused project, from the builds kept while it was paused | Full | | | `delete_project` | Deletes a project with its deployments, build logs, environment variables and feature flags. Its addresses stop answering; its domains stay in the team. It can't be undone | Full | Yes: deletes it | ## Deployments | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_deployments` | Lists deployments newest first, of one project or the whole team, with what production serves now. Filter by environment, state, branch or words | Read | | | `get_deployment` | Shows one deployment: its state, environment, commit, build steps with their times, its URL and domains, and, if it failed, where and why | Read | | | `get_deployment_logs` | Reads a deployment's build log: from a line on, or the last lines, where an error usually is | Read | | | `wait_for_deployment` | Waits up to about a minute for a build to finish (ready, failed or canceled), with progress | Read | | | `deploy_branch` | Builds the newest commit of a Git project's branch. The production branch makes a production deployment; another branch makes a preview | Full | Yes: can change production | | `deploy_folder` | Local server only. Zips a folder on your computer (without `node_modules`, `.git`, `.next` and what `.orbitsignore` lists), uploads it to an upload project and builds it for production | Full | Yes: changes production | | `redeploy` | Builds a deployment's commit (or upload) again, as a new deployment in the same environment. Use it after changing environment variables | Full | Yes: can change production | | `promote_deployment` | Builds a preview's commit for production; production serves it once it is ready. It also lifts the pause a rollback set | Full | Yes: changes production | | `rollback_production` | Makes production serve an earlier production deployment at once, with no build, and pauses automatic production deploys until a promote or a new production deploy | Full | Yes: changes production | | `cancel_deployment` | Stops a queued or building deployment. What production serves doesn't change | Full | | `deploy_folder`'s preview says how many files it would send and names any that look like secrets, such as `.env` files and keys, so you can leave them out with a `.orbitsignore` file first. See [Upload a folder](https://docs.orbits.africa/getting-started/upload-a-folder). Builds take a while. A tool waits up to about a minute, then gives your app the deployment's or operation's id, and the app follows it with `wait_for_deployment` or `wait_for_operation`. ## Environment variables | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_env_vars` | Lists a project's variables: each key, its environments, whether it is sensitive, and whether it changed since the latest deployment. Never their values | Read | | | `set_env_var` | Adds a variable, sensitive (write-only) by default, or replaces one. The value is never shown back. It applies to deployments built afterwards | Full | | | `delete_env_var` | Deletes a variable. `restore_env_var` brings it back within 10 minutes | Full | Yes: deletes it | | `restore_env_var` | Brings back a variable deleted in the last 10 minutes, with its value and environments | Full | | | `reveal_env_var` | Reads the value of one non-sensitive variable into the conversation. Every reveal is recorded in the team's activity | Full | Yes: shows a secret | Sensitive variables, the default, can never be read back, by any tool. See [Environment variables](https://docs.orbits.africa/deploy/environment-variables). ## Domains and DNS | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_domains` | Lists the team's domains: what each serves or redirects to, its state, whether it uses Orbits DNS, the record it needs, and its certificate | Read | | | `get_domain_checks` | Says whether a domain is set up: its state, the record or nameservers it needs, what the last DNS lookup found, and its certificate. It can look the DNS up again now | Full to look again; Read otherwise | | | `add_domain` | Adds a domain to serve a project's production or a branch's preview, or to redirect. The preview says which record or nameservers it will need | Full | Yes: changes DNS | | `remove_domain` | Removes a domain from the team: it stops answering within a minute. For an Orbits DNS zone, its records go too | Full | Yes: removes it | | `list_dns_records` | Lists the records of a domain on Orbits DNS, and whether Orbits manages each one for a project | Read | | | `add_dns_record` | Adds an A, AAAA, CNAME, MX, TXT or CAA record to a domain on Orbits DNS | Full | Yes: changes DNS | | `update_dns_record` | Replaces a record with a new type, name, value and TTL | Full | Yes: changes DNS | | `delete_dns_record` | Deletes a record | Full | Yes: deletes it | Records Orbits manages for a project can't be changed or deleted. DNS changes can take minutes to reach everyone. See [Custom domains](https://docs.orbits.africa/domains/custom-domains) and [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns). ## Feature flags | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_flags` | Lists a project's flags with each one's type and, per environment, whether it is on, its rollout or value, and its targeting rules | Read | | | `set_flag` | Changes a flag in one environment: turns a boolean flag on or off and sets its rollout, or sets a string or number flag's value. Apps read the change within seconds, without a deploy | Full | | See [Feature flags](https://docs.orbits.africa/features/flags). ## Workflows | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `list_workflows` | Lists the workflows the production deployment defines, with each one's trigger, retries, last run and success rate | Read | | | `list_workflow_runs` | Lists a project's recent runs, newest first, with state, trigger, timing and error | Read | | | `get_workflow_run` | Shows a run with its steps, attempts, input, output and error | Read | | | `run_workflow` | Starts a run on the production deployment, with an optional JSON input. The workflow is your app's code and does what it was written to do | Full | | | `retry_workflow_run` | Retries a failed run from its failed step; steps that succeeded don't run again | Full | | | `cancel_workflow_run` | Cancels a running run: no further steps run, and steps already done are not undone | Full | | See [Workflows](https://docs.orbits.africa/features/workflows). ## Logs and insights | Tool | What it does | Access | Asks first | | --- | --- | --- | --- | | `get_runtime_logs` | Reads a project's runtime logs, newest first: requests and function output, over the last hour by default. Filter by words, source, level or status | Read | | | `get_request_metrics` | A project's request counts, error rates and latency over a range, by route, status and region | Read | | | `get_analytics` | A project's visitors and page views, with top pages, referrers, countries, devices and custom events, against the period before. Needs Analytics on, on the Pro plan | Read | | | `get_speed_insights` | A project's Core Web Vitals from real visits (LCP, INP, CLS, FCP, TTFB), by page, on mobile or desktop. Needs Speed Insights on, on the Pro plan | Read | | See [Runtime logs](https://docs.orbits.africa/observe/runtime-logs), [Analytics](https://docs.orbits.africa/observe/analytics) and [Speed Insights](https://docs.orbits.africa/observe/speed-insights). ## Built-in prompts and the guide Some apps show these as shortcuts: - `fix_failed_deployment`: find out why a project's latest deployment failed, and propose a fix. - `connect_domain`: add a custom domain to a project and walk through the DNS setup. - `health_check`: review a project's recent errors, latency and deployments, and summarise what needs attention. - `deploy_this_folder` (local server only): deploy a folder on your computer to an upload project. The server also offers a short guide to how Orbits works, as `orbits://docs/guide`, so the app can read it. ## What it can never do Some things return many secrets at once, or act on your team's people, tokens, money or connections. There is no tool for these, and the server's tests fail if any tool reaches them. Do them yourself: | Not available | Where to do it instead | | --- | --- | | Read every variable's value at once (`env pull`) | `orbits env pull` in the [CLI](https://docs.orbits.africa/cli#environment-variables) | | Read a project's flag keys | The web app | | Create, see or revoke API tokens | [API tokens](https://docs.orbits.africa/team/api-tokens) in the web app | | Invite, remove or change members | [Teams and roles](https://docs.orbits.africa/team/teams-and-roles) in the web app | | Change the plan, pay, or see invoices | [Paying](https://docs.orbits.africa/billing/paying) in the web app | | Install or change integrations | [Integrations](https://docs.orbits.africa/team/integrations) in the web app | | Move a project to another team, or delete the team | The web app | It also never shows your payment card's details, even in `get_billing`. Anything the tables don't list is done in the web app, the [CLI](https://docs.orbits.africa/cli) or the [API](https://docs.orbits.africa/api). --- # AI apps and security Source: https://docs.orbits.africa/ai/ai-apps-security What a connected AI app can and cannot do, how two-step confirmations work, how to limit an app and disconnect it, and what the Orbits MCP server never shows. When you connect an AI app, the web app makes it an [API token](https://docs.orbits.africa/team/api-tokens) of its own. That token decides everything the app can do. This page explains how to keep it small, and how to take it away. ## Access You choose one when you approve the app. | Access | Scope | The app can | | --- | --- | --- | | **Read only** | `read` | See projects, deployments, logs, usage and settings. Change nothing, and read no secret value | | **Full access** | `full` | Also deploy, roll back, change variables, domains, DNS and flags, run workflows and delete. The steps that matter [ask you first](#two-step-confirmations) | Pick the lowest access that does the job. **Read only** is enough for "why did the build fail?" and "how much traffic did we get this week?". The approval page starts on **Full access** unless the app asked only to read; change it before you press **Allow**. The access is enforced by the Orbits API, not by the app or the MCP server. A **Read only** app that tries to change something gets an error saying its token is read-only, and nothing changes. ## Expiry An AI app's access lasts 30 days, 90 days (the default) or a year. There is no "never", and no renewal in the background: when it ends, the app's calls are refused and it asks you to approve it again. ## See and disconnect AI apps Each connected app is an API token in the team's **Settings › API tokens**, named after the app, like `Claude-Code-MCP` or `Cursor-MCP`. The list shows its access, when it was created, when it was last used and when it expires. To disconnect an app, press **Revoke** on its row, then **Revoke token**. On the hosted server it stops working within about 30 seconds. To use the app again, connect it again. Owners and admins can see and revoke tokens. Removing the server from the app alone doesn't end the token: revoke it too. ## Two-step confirmations Through the Orbits MCP server, anything that deletes something, changes what production serves (deploy, redeploy, promote, roll back, pause), adds or changes a domain or DNS record, or shows a secret value takes two calls: 1. The first call changes nothing. It returns a preview of what will happen and a `confirmation_token`. 2. Your app shows you the preview, and calls again with the token only after you say yes. The `confirmation_token` is signed by the server and bound to: - the tool, - the exact details of the request, - your connection's API token. It works **once** and expires after **5 minutes**. It can't be used for other details, another tool or another connection. The server never confirms on its own. A confirmed change that is retried, for example after a network error, is not made twice. [The tools that ask first](https://docs.orbits.africa/ai/mcp-tools#it-asks-before-it-changes-production-dns-or-deletes). ## What an AI app can never do Whatever its access: - It works in one team, the one you chose. - It can never do more than the token allows, and a token can never do more than the team's owners and admins can. - It can't read the values of sensitive variables, which are write-only for everyone. It can read one non-sensitive value at a time with `reveal_env_var`, with **Full access**, after you confirm; every reveal is recorded in the team's [activity](https://docs.orbits.africa/team/activity). - It can't read every variable at once, or a project's flag keys. - It can't create, see or revoke API tokens, or manage members and invites. - It can't change the plan, pay, or see your card's details. - It can't install or change integrations, move a project to another team, or delete the team. [The full list](https://docs.orbits.africa/ai/mcp-tools#what-it-can-never-do). ## What the server does with your token On the hosted server, `https://mcp.theorbits.app/mcp`, each request's token is passed to the Orbits API for that request only. It is never stored or logged. The server's logs record the request, the tool, how long it took and how it ended, never the details you sent, the results or tokens. A token that is unknown, expired or revoked gets a sign-in error, so the app asks you to sign in again. The [local server](https://docs.orbits.africa/ai/connect-your-ai#run-it-locally) uses the token you give it, or the one the CLI stored, and sends it only to the Orbits API. It refuses a CLI settings file that other users on the computer could change, and an API address that isn't `https`. Every call the server makes is marked `orbits-mcp`, which **Settings › API tokens** shows as the token's last use. ## Be careful with what the app reads An AI app reads what tools return, and that includes text someone else could have written: a commit message, a build log line, a runtime log line, a project or domain name, a DNS value, a workflow's input or output. Someone could hide an instruction in that text, such as "delete every project". This is called prompt injection. The Orbits server labels such text as data from the account, not instructions, and keeps it out of the summary a preview is read from. But no AI app is perfect. To stay safe: - Use **Read only** unless you need more. - Don't give **Full access** to an app that also reads email, the web or files you didn't write. - Read every preview before you say yes. If you didn't ask for it, say no. - Use a short expiry for anything that can write. ## "Not verified by Orbits" Anyone can build an AI app and give it any name. The approval page shows the name the app gave itself, with **Not verified by Orbits** next to it. It means Orbits hasn't checked who made the app. Before you press **Allow**, check: - that you started this connection yourself, just now (the page says "Only continue if you started connecting this app yourself"); - the address the page says it will send you back to. If anything looks wrong, cancel. ## Errors | What the app says | What it means | What to do | | --- | --- | --- | | The token is read-only | The app was connected with **Read only** | Reconnect it with **Full access**, or do it yourself in the web app or [CLI](https://docs.orbits.africa/cli) | | Orbits refuses this to API tokens | No token can do this, by design | Do it in the web app | | Orbits did not accept the API token | The connection expired or was revoked | Reconnect the app | | The team's plan does not include this | It needs the Pro plan | An owner can upgrade under **Team › Billing**. See [Plans](https://docs.orbits.africa/billing/plans) | | Orbits is rate limiting these requests | Too many requests at once | Wait the time it says, then ask again | More fixes, app by app: [Troubleshooting](https://docs.orbits.africa/ai/troubleshooting). --- # Troubleshooting AI apps Source: https://docs.orbits.africa/ai/troubleshooting Fixes for the problems people hit most when connecting an AI app to Orbits. Find the message you see, then follow the fix. ## The browser did not open Some apps open the approval page only when you ask them to sign in. - **Claude:** in **Settings › Connectors**, press **Connect** on the Orbits connector. - **ChatGPT:** open the connector in **Settings › Connectors** and connect it. If you don't see **Create**, turn on developer mode under **Advanced**. - **Claude Code:** run `/mcp`, choose **orbits**, then sign in. - **Codex:** run `codex mcp login orbits`. - **Cursor:** in Cursor's MCP settings, press **Connect** next to **orbits**. - **VS Code:** start the **orbits** server when VS Code asks. - **Windsurf:** refresh Windsurf's MCP servers. - **Gemini CLI:** restart it. It finds the sign-in on its own on first use. - **Over SSH or a remote desktop:** the browser opens on the machine running the app. Sign in there, or [run the server locally](https://docs.orbits.africa/ai/connect-your-ai#run-it-locally) with a token. ## "This connection request can't be used" The app sent a request Orbits can't trust: an ID Orbits didn't issue, or an address to send you back to that the app never registered. Nothing was sent to the app. Remove Orbits from the app, add it again, and start over. ## "Start from your AI app" The approval page has no connection waiting. Requests expire after ten minutes. Go back to the app and connect Orbits again. ## The page says only owners and admins can connect An AI app acts for a team with an API token, and only a team's owners and admins can create one. Ask an owner of your team to make you an admin, or create a team of your own, then connect the app again. See [Teams and roles](https://docs.orbits.africa/team/teams-and-roles). ## "That's a lot of approvals in a minute" You approved too many connections in a short time. Wait the number of seconds it says, then try again. ## It worked, then started failing If the app says Orbits did not accept the API token, the connection expired (after 30 days, 90 days or a year) or someone revoked it. Nothing is wrong with your account. Reconnect the app: remove the Orbits server and add it again, or use the app's sign-in action above, and approve it again in the browser. For [Grok](https://docs.orbits.africa/ai/connect-your-ai#set-up-your-app) and the [local server](https://docs.orbits.africa/ai/connect-your-ai#run-it-locally), the API token it uses expired or was revoked. Make a new one under **Team › Settings › API tokens**, or run `orbits login` again. ## The token is read-only The app was connected with **Read only**, so it can't change anything or read a variable's value. Either: - do it yourself in the web app or the [CLI](https://docs.orbits.africa/cli), or - reconnect the app with **Full access**. [Access](https://docs.orbits.africa/ai/ai-apps-security#access). For the local server, use a full-access token. ## Orbits refuses this to API tokens Some things no API token can do, by design: managing tokens and members, billing, integrations, and deleting the team. Do them in the web app at [orbits.africa](https://orbits.africa). [What an AI app can never do](https://docs.orbits.africa/ai/ai-apps-security#what-an-ai-app-can-never-do). ## The team's plan does not include this The tool needs a feature of the Pro plan, such as Analytics or Speed Insights. Nothing was changed. An owner can upgrade under **Team › Billing** in the web app. See [Plans](https://docs.orbits.africa/billing/plans). ## Not found Check the project's slug or the deployment's id: ask the app to list them first. Not found also means it isn't in the connection's team, or, for a token limited to one project, isn't that project. ## Too many requests The app sent requests faster than its limit allows. The error says how long to wait. Wait that long, then ask again. Asking for fewer things at once helps, for example "list my projects" instead of one project at a time. ## The app says a confirmation was not valid Tools that delete, change production, change DNS or show a secret [ask first](https://docs.orbits.africa/ai/mcp-tools#it-asks-before-it-changes-production-dns-or-deletes). The `confirmation_token` in the preview lasts 5 minutes, works once, and works only for that exact request. If it has expired, was already used, or the app changed any detail, nothing is done. Ask the app to start again, check the new preview, then say yes. ## The build is still running Tools wait up to about a minute for a build or a change. If it is still going, the app gets the deployment's or operation's id and should carry on with `wait_for_deployment` or `wait_for_operation`. Ask it to keep waiting, or follow the build with `orbits logs -f` in the [CLI](https://docs.orbits.africa/cli#logs). ## A new variable isn't used Environment variables apply to deployments built after you change them. Ask the app to redeploy, which [asks first](https://docs.orbits.africa/ai/mcp-tools#deployments) if it changes production. ## The app can't deploy a folder Only the [local server](https://docs.orbits.africa/ai/connect-your-ai#run-it-locally) can deploy a folder from your computer (`deploy_folder`), and only to an upload project. A Git project deploys from its repository: push, or ask the app to deploy a branch. ## The local server will not start - `orbits-mcp: command not found`: install `orbits-mcp`, and make sure it is on your `PATH`. `orbits mcp status` tells you if it is found. - No token found: run `orbits login`, or set `ORBITS_TOKEN`. - Wrong team: set `ORBITS_PROFILE` to the CLI profile you want, or `ORBITS_TEAM`. - It refuses the CLI's settings file: the file can be changed by other users on the computer. Make it yours only, for example with `chmod 600`. ## Orbits could not do this just now A temporary problem on the Orbits side. Try again in a moment. If it keeps happening, [contact support](https://docs.orbits.africa/help/support). ## Still stuck Every error from Orbits includes a request id. [Contact support](https://docs.orbits.africa/help/support) and include it. --- # SDKs Source: https://docs.orbits.africa/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](https://docs.orbits.africa/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](https://docs.orbits.africa/sdks/javascript) | `npm install @useorbits/sdk` | `import { Orbits } from "@useorbits/sdk"` | | [Python](https://docs.orbits.africa/sdks/python) | `pip install useorbits` | `import useorbits` | | [Go](https://docs.orbits.africa/sdks/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](https://github.com/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](https://docs.orbits.africa/team/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](https://docs.orbits.africa/api/conventions). - **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](https://docs.orbits.africa/api/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](https://docs.orbits.africa/getting-started/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. :::warning[Keep the token on the server] Never put an API token in code that runs in a browser. Anyone can read it there. ::: ## 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](https://docs.orbits.africa/cli) may be simpler. To let an AI app manage your projects, see [Connect your AI](https://docs.orbits.africa/ai/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](https://docs.orbits.africa/observe/analytics), [Speed Insights](https://docs.orbits.africa/observe/speed-insights), [Feature flags](https://docs.orbits.africa/features/flags) and [Workflows](https://docs.orbits.africa/features/workflows). ::::cards :::card[JavaScript]{href=/sdks/javascript} Node.js 20+, Bun and Deno. No dependencies. ::: :::card[Python]{href=/sdks/python} Python 3.10 or later. Sync and async clients. ::: :::card[Go]{href=/sdks/go} Go 1.23 or later. No dependencies outside the standard library. ::: :::: --- # JavaScript and TypeScript SDK Source: https://docs.orbits.africa/sdks/javascript Install @useorbits/sdk, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries. ```ts import { Orbits } from "@useorbits/sdk"; const orbits = new Orbits(); for await (const project of orbits.projects.listAll("my-team")) { console.log(project.slug, project.status, project.production_url); } ``` `@useorbits/sdk` is the official JavaScript library, with TypeScript types generated from the API's OpenAPI contract. It has no runtime dependencies and uses the global `fetch`, so it runs on Node.js 20 or later, Bun and Deno. It ships as ESM and CommonJS. Request and response fields are exactly as the API sends them (`source_kind`, `next_cursor`); method names are camelCase. `team` is a team's slug or `team_` id, and `project` a project's slug or `prj_` id. ## Install ```console $ npm install @useorbits/sdk ``` ## Authenticate Make an [API token](https://docs.orbits.africa/team/api-tokens) under **Team › Settings › API tokens** and put it in `ORBITS_TOKEN`. The client reads it. ```console $ export ORBITS_TOKEN=orb_live_… ``` Without a token, `new Orbits()` throws. Or pass options: ```ts const orbits = new Orbits({ token: process.env.MY_ORBITS_TOKEN, baseUrl: "https://stagingapi.theorbits.app/v1", // or ORBITS_API_URL; default https://api.theorbits.app/v1 maxRetries: 3, // the default timeout: 60_000, // per attempt, in milliseconds (the default) userAgent: "my-deployer/1.0", // default orbits-js/ }); ``` `fetch` sets your own fetch. Every method also takes per-call options last: `{ signal, timeout, maxRetries, idempotencyKey, headers }`. :::warning[Keep the token on the server] Never put an API token in code that runs in a browser. Anyone can read it there. ::: ## Deploy and follow the build For a Git project, `deployments.create` builds a branch's newest commit, by default the production branch: ```ts title="deploy.ts" import { Orbits } from "@useorbits/sdk"; const orbits = new Orbits(); const deployment = await orbits.deployments.create("my-team", "my-app"); // or a preview: orbits.deployments.create("my-team", "my-app", { branch: "feature/checkout" }) for await (const event of orbits.deployments.streamLogs("my-team", "my-app", deployment)) { if (event.type === "line") console.log(event.line.text); if (event.type === "done") console.log(`Build ${event.state} in ${event.duration_seconds}s`); } const ready = await orbits.waitForDeployment("my-team", "my-app", deployment); console.log(ready.url); ``` `streamLogs` follows the build log as it is written, reconnects where it left off if the connection drops, and ends after `done`. Breaking out of the loop, or aborting `signal`, closes the stream. For a finished build, `deployments.listAllLogs(team, project, deployment)` pages through the whole log. `deployments.get(team, project, deployment)` reads one deployment. ### Deploy a folder Projects created with `source_kind: "upload"` deploy from files instead of a repository. `uploadDir`, from `@useorbits/sdk/node`, zips a folder and deploys it to production: ```ts import { Orbits } from "@useorbits/sdk"; import { uploadDir } from "@useorbits/sdk/node"; const orbits = new Orbits(); await orbits.projects.create("my-team", { name: "my-site", source_kind: "upload" }); const { deployment } = await uploadDir(orbits, "my-team", "my-site", "./dist"); await orbits.waitForDeployment("my-team", "my-site", deployment); ``` It leaves out `node_modules`, `.git`, `.next` and `__MACOSX`, and whatever the folder's `.orbitsignore` lists (`.gitignore` syntax). Everything else is uploaded, `.env` files included, so list those in `.orbitsignore` unless the build needs them. Symbolic links are left out and reported in `skipped`. An upload may be up to 100 MB zipped and 20,000 files. `@useorbits/sdk/node` uses Node.js built-ins (Node.js, Bun, and Deno with `node:` modules). Anywhere else, zip the files yourself and call `orbits.deployments.upload(team, project, zipBytes, { filename })`. ### Promote, roll back, redeploy ```ts await orbits.deployments.promote("my-team", "my-app", "dpl_…"); // a preview to production, as a new build await orbits.deployments.redeploy("my-team", "my-app", "dpl_…", { use_cache: false }); await orbits.deployments.cancel("my-team", "my-app", "dpl_…"); const change = await orbits.deployments.rollback("my-team", "my-app", "dpl_…"); // at once, no build console.log(change.undo); // pass to deployments.setProduction to undo it ``` A rollback pauses automatic production deploys. See [Deployments](https://docs.orbits.africa/deploy/deployments). ## Environment variables ```ts await orbits.env.create("my-team", "my-app", { variables: [ { key: "STRIPE_SECRET_KEY", value: process.env.STRIPE_SECRET_KEY ?? "" }, // sensitive by default { key: "API_URL", value: "https://api.example.com", sensitive: false, environments: ["production"] }, ], }); for await (const v of orbits.env.listAll("my-team", "my-app")) { console.log(v.key, v.environments, v.sensitive); } ``` Variables are sensitive (write-only) unless `sensitive: false`, and apply to production and preview unless you set `environments`. A key that exists already fails with a `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` an environment's readable values, both with a full-access token. See [Environment variables](https://docs.orbits.africa/deploy/environment-variables). ## Domains ```ts const domain = await orbits.domains.add("my-team", { domain: "shop.example.com", project: "my-app" }); console.log(domain.state, domain.required_record); const checked = await orbits.domains.check("my-team", "shop.example.com"); // look the DNS up again now ``` `branch` serves a branch's newest preview instead of production, and `to` redirects to another hostname. Records on [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) are under `domains.records` (`list`, `add`, `replace`, `delete`). See [Custom domains](https://docs.orbits.africa/domains/custom-domains). ## Resources | Area | Methods | | --- | --- | | Me | `me.get()` | | Teams | `teams.list/listAll/get/update/overview`, `teams.notifications.list/listAll/markRead` | | Projects | `projects.list/listAll/create/get/update/delete/deletionImpact/pause/resume/branchAddresses` | | Deployments | `deployments.list/listAll/listForTeam/listAllForTeam/create/get/redeploy/promote/rollback/cancel/setProduction`, `deployments.logs/listAllLogs/streamLogs/screenshot`, `deployments.upload`, `deployments.uploads.start/complete/cancel`, `deployments.wait` | | Environment variables | `env.list/listAll/create/update/delete/restore/reveal/pull` | | Domains | `domains.list/preview/add/get/update/remove/check/importZone`, `domains.records.list/add/replace/delete`, `domains.email.get/set` | | Flags | `flags.list/create/get/update/delete/keys/setEnvironment`, `flags.rules.add/update/remove` | | Workflows | `workflows.list/run`, `workflows.runs.get/cancel/retry` | | Alerts | `alerts.list/create/preview/update/delete`, `alerts.events.list/listAll`, `alerts.channels.get/setWebhook/deleteWebhook/testWebhook` | | Observability | `observability.get`, `observability.runtimeLogs.list/listAll/get`, `observability.analytics.get/event/set`, `observability.speedInsights.get/set` | | Usage, activity | `usage.get(team, { month })`, `activity.list/listAll` | | Billing (reads) | `billing.listPlans`, `billing.get`, `billing.invoices.list/get` | | Templates, integrations | `templates.list()`, `integrations.list(team)` | | Operations | `operations.get/wait`, `waitForOperation`, `waitForDeployment` | There are `sandboxes` methods too, but sandboxes are not available yet. ## Errors Every error is an `OrbitsError` with the API's problem document: `status`, `title`, `detail`, `code`, `requestId`, `errors` (the fields of a `422`) and `problem`. Show `detail` to people; branch on the class or the `code`: ```ts import { ForbiddenError, isOrbitsError, ValidationError } from "@useorbits/sdk"; try { await orbits.projects.create("my-team", { name: "my-app", source_kind: "upload" }); } catch (err) { if (err instanceof ValidationError) for (const e of err.errors) console.log(e.field, e.message); else if (err instanceof ForbiddenError) console.log(err.reason); // e.g. "This API token is read-only" else if (isOrbitsError(err, "plan_required")) console.log("Needs Pro"); else throw err; } ``` | Class | When | | --- | --- | | `BadRequestError` | `400` | | `AuthenticationError` | `401`: the token is wrong, revoked or expired | | `PlanRequiredError` | `402`: the team's plan doesn't include this (`requiredPlan`, `feature`) | | `ForbiddenError` | `403`, with the API's `reason` | | `NotFoundError` | `404`: not there, or not in the token's team. The API answers the same for both | | `ConflictError` | `409` | | `ValidationError` | `422`, with `errors[{ field, message }]` | | `RateLimitedError` | `429` after the retries, with `retryAfterSeconds` and `scope` | | `ServerError` | `5xx` after the retries | | `ConnectionError`, `TimeoutError` | No answer | A response that isn't the API's own error (a proxy's error page, say) is never shown: the message says what the status means and gives the request id. [Errors](https://docs.orbits.africa/api/errors). ## Pages `list()` returns one page (`{ items, next_cursor }`). `listAll()` follows the cursor for you, fetching each page only when the loop gets there: ```ts for await (const d of orbits.deployments.listAll("my-team", "my-app", { environment: "production" })) { console.log(d.id, d.state); } ``` ## Waiting Slow changes answer `202` with an operation or the new deployment: ```ts const op = await orbits.projects.delete("my-team", "old-site"); await orbits.waitForOperation(op); // rejects with OperationFailedError if it failed const d = await orbits.deployments.redeploy("my-team", "my-app", "dpl_…"); await orbits.waitForDeployment("my-team", "my-app", d, { timeoutMs: 15 * 60_000, onUpdate: (x) => console.log(x.state) }); ``` Both poll every 2 seconds and give up after 30 minutes with a `WaitTimeoutError`; the change may still finish. Options: `{ timeoutMs, pollIntervalMs, signal, onUpdate }`. `waitForDeployment` resolves when the deployment is `ready`, and rejects with `DeploymentFailedError` (with the build's failure in the message) when it ends `failed` or `canceled`; pass `throwOnFailure: false` to get the deployment back instead. ## Idempotency and retries Every `POST` carries an `Idempotency-Key`, a random UUID or yours via `idempotencyKey`, and every retry of that call reuses it, so a change can't happen twice. Connection errors, timeouts, `429`, `502`, `503` and `504` are retried up to `maxRetries` times with a growing, random wait, or after `Retry-After` when the API sends it (at most a minute). The token is sent only to the API, never to the storage address an upload goes to, and is kept out of the client's printed form. The SDK never logs anything. ## Calling any endpoint `request` calls a path directly, with the same auth, retries and errors: ```ts const page = await orbits.request({ method: "GET", path: "/teams/my-team/projects", query: { q: "shop" } }); ``` --- # Python SDK Source: https://docs.orbits.africa/sdks/python Install useorbits, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries, sync or async. ```python 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 ```console $ pip install useorbits ``` ## Authenticate Make an [API token](https://docs.orbits.africa/team/api-tokens) under **Team › Settings › API tokens** and put it in `ORBITS_TOKEN`. The client reads it. ```console $ export ORBITS_TOKEN=orb_live_… ``` Without a token, `useorbits.Orbits()` raises. Or pass options: ```python 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: ```python title="deploy.py" 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: ```python 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 ```python 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](https://docs.orbits.africa/deploy/deployments). ## Environment variables ```python 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](https://docs.orbits.africa/deploy/environment-variables). ## Domains ```python 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 now ``` `branch=` serves a branch's newest preview instead of production, and `to=` redirects to another hostname. Records on [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) are under `domains.records`. See [Custom domains](https://docs.orbits.africa/domains/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: ```python 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 ```python 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](https://docs.orbits.africa/api/errors). ## Pages `list()` returns one page, with `items` and `next_cursor`. `list_all()` follows the cursor for you: ```python 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: ```python 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/`. The token is never logged. ## Calling any endpoint `request` calls a path directly, with the same auth, retries and errors: ```python page = orbits.request("GET", "/teams/my-team/projects", query={"q": "shop"}) ``` --- # Go SDK Source: https://docs.orbits.africa/sdks/go Install orbits-go, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries. ```go c, err := orbits.NewFromEnv() if err != nil { log.Fatal(err) } for p, err := range c.Projects.All(ctx, "my-team", nil) { if err != nil { log.Fatal(err) } fmt.Println(p.Slug, p.Status) } ``` `orbits-go` is the official Go library, with types generated from the API's OpenAPI contract. It has no dependencies outside the standard library, and needs Go 1.23 or later: lists and the build log are Go iterators. The [Orbits CLI](https://docs.orbits.africa/cli) and MCP server are built on it. `team` is a team's slug or `team_` id, and `project` a project's slug or `prj_` id. ## Install ```console $ go get github.com/The-Orbits/orbits-go ``` ```go import orbits "github.com/The-Orbits/orbits-go" ``` ## Authenticate Make an [API token](https://docs.orbits.africa/team/api-tokens) under **Team › Settings › API tokens** and put it in `ORBITS_TOKEN`. `NewFromEnv` reads it, and `ORBITS_API_URL` if it is set. ```console $ export ORBITS_TOKEN=orb_live_… ``` Or pass the token yourself, with options: ```go c, err := orbits.New(token, orbits.WithBaseURL("https://stagingapi.theorbits.app/v1"), orbits.WithUserAgent("my-deployer/1.0"), ) ``` | Option | What it does | | --- | --- | | `WithBaseURL(url)` | The API's base URL, with `/v1`. Default `https://api.theorbits.app/v1` | | `WithUserAgent(product)` | Puts your tool's name before the SDK's, like `my-deployer/1.0 orbits-go/0.1.0`. **Settings › API tokens** shows it as the token's last use | | `WithHTTPClient(h)` | Your `*http.Client`. Its `Timeout` bounds each attempt (default 60 seconds) | | `WithMaxRetries(n)` | Retries after the first try. Default 3; 0 turns them off | | `WithHeader(k, v)` | A header on every request | Per call, `orbits.WithIdempotencyKey(key)`, `orbits.WithRequestHeader(k, v)` and `orbits.WithNoRetry()` go after the other arguments. The token is sent only in the `Authorization: Bearer` header. The SDK never logs it or variable values, and printing a `Client` doesn't show it. `c.Me.Get(ctx)` says who the token acts as. ## Deploy and follow the build For a Git project, `Deployments.Create` builds a branch's newest commit, by default the production branch: ```go title="main.go" package main import ( "context" "fmt" "log" orbits "github.com/The-Orbits/orbits-go" ) func main() { ctx := context.Background() c, err := orbits.NewFromEnv() if err != nil { log.Fatal(err) } d, err := c.Deployments.Create(ctx, "my-team", "my-app", orbits.CreateDeploymentRequest{}) // or a preview: orbits.CreateDeploymentRequest{Branch: orbits.Ptr("feature/checkout")} if err != nil { log.Fatal(err) } for ev, err := range c.Deployments.StreamLogs(ctx, "my-team", "my-app", d.ID, nil) { if err != nil { log.Fatal(err) } if ev.Type == orbits.LogEventLine { fmt.Println(ev.Line.Text) } } final, err := c.Deployments.Wait(ctx, "my-team", "my-app", d.ID, nil) // *orbits.DeploymentError if it failed if err != nil { log.Fatal(err) } if final.URL != nil { fmt.Println(*final.URL) } } ``` `StreamLogs` yields `line`, `steps` and `done` events and stops after `done`; a finished build answers at once. When the connection drops, it reconnects from the last line it received, without gaps or repeats. `ListLogs` pages through a finished build's log instead. `Deployments.Get(ctx, team, project, deployment)` reads one deployment. ### Deploy a folder ```go kind := orbits.ProjectSourceKindUpload _, err := c.Projects.Create(ctx, "my-team", orbits.ProjectCreate{Name: "my-site", SourceKind: &kind}) if err != nil { return err } d, err := c.Deployments.UploadDir(ctx, "my-team", "my-site", "./dist", nil) ``` `UploadDir` zips the folder's contents, leaving out `node_modules`, `.git`, `.next`, `__MACOSX`, `.DS_Store`, `.orbits` and the patterns of the folder's `.orbitsignore` (`.gitignore` syntax). It refuses links and special files, and checks the limits (a zip of up to 100 MiB, 500 MiB and 20,000 files unpacked) before sending anything. Then it sends the zip straight to storage, without your token, and returns the queued production deployment. `UploadZip` sends a zip you already have; `ZipDir` only builds one. Set `UploadOptions.IdempotencyKey` when you may retry the whole deploy, so a retry gets the same upload instead of a second. Only projects created with `SourceKind: upload` take uploads. A Git project deploys with `Deployments.Create`, `Redeploy`, or a push. ### Promote, roll back, redeploy ```go _, err = c.Deployments.Promote(ctx, "my-team", "my-app", "dpl_…") // a preview to production, as a new build _, err = c.Deployments.Rollback(ctx, "my-team", "my-app", "dpl_…") // at once, no build _, err = c.Deployments.Redeploy(ctx, "my-team", "my-app", "dpl_…", orbits.RedeployRequest{UseCache: orbits.Ptr(false)}) _, err = c.Deployments.Cancel(ctx, "my-team", "my-app", "dpl_…") ``` A rollback pauses automatic production deploys. See [Deployments](https://docs.orbits.africa/deploy/deployments). ## Environment variables ```go _, err = c.Env.Create(ctx, "my-team", "my-app", orbits.EnvVarCreate{ Variables: []orbits.EnvVarInput{ {Key: "STRIPE_SECRET_KEY", Value: os.Getenv("STRIPE_SECRET_KEY")}, // sensitive by default {Key: "API_URL", Value: "https://api.example.com", Sensitive: orbits.Ptr(false), Environments: []orbits.EnvironmentName{orbits.EnvironmentNameProduction}}, }, }) for v, err := range c.Env.All(ctx, "my-team", "my-app", nil) { if err != nil { return err } fmt.Println(v.Key, v.Environments, v.Sensitive) } ``` Variables are sensitive (write-only) unless `Sensitive` is false, and apply to production and preview unless you set `Environments`. With `Create`, a key that exists already is a conflict (`orbits.IsConflict`) and nothing is saved; `Env.Set` replaces existing keys instead. 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` an environment's readable values, both with a full-access token. See [Environment variables](https://docs.orbits.africa/deploy/environment-variables). ## Domains ```go dom, err := c.Domains.Add(ctx, "my-team", orbits.AddDomainRequest{ Domain: "shop.example.com", Project: orbits.Ptr("my-app"), }) if err != nil { return err } fmt.Println(dom.State) dom, err = c.Domains.Check(ctx, "my-team", "shop.example.com") // look the DNS up again now ``` `Branch` serves a branch's newest preview instead of production, and `To` redirects to another hostname. `RequiredRecord` is the record to add at your DNS provider. Records on [Orbits DNS](https://docs.orbits.africa/domains/orbits-dns) are `ListRecords`, `AddRecord`, `ReplaceRecord` and `DeleteRecord`. See [Custom domains](https://docs.orbits.africa/domains/custom-domains). ## Services `c.Me`, `c.Teams`, `c.Projects`, `c.Deployments`, `c.Env`, `c.Domains` (with DNS records, checks, zone imports, email setup and branch addresses), `c.Flags`, `c.Workflows`, `c.Alerts`, `c.Observability` (runtime logs, metrics, Analytics, Speed Insights), `c.Usage`, `c.Activity`, `c.Billing`, `c.Templates`, `c.Operations` and `c.Integrations`. There is a `c.Sandboxes` too, but sandboxes are not available yet. Request types follow the API's field names. Optional fields are pointers, and a nil one is not sent; `orbits.Ptr` sets one inline. Enums are typed string constants, such as `orbits.ProjectSourceKindUpload`. To send `null` (to clear a value), name the field in the request's `NullFields`: ```go _, err := c.Domains.Update(ctx, "my-team", "shop.example.com", orbits.UpdateDomainRequest{NullFields: []string{"to"}}) ``` ## Errors Every API error is an `*orbits.Error` with `Status`, `Title`, `Detail`, `RequestID`, `Code`, `Errors` (the fields of a `422`), `RequiredPlan` and `Feature` (on a `402`), `RetryAfter` and `RateLimitScope`. `Detail` is plain language and safe to show. ```go p, err := c.Projects.Get(ctx, "my-team", "my-app") switch { case orbits.IsNotFound(err): // not there, or not in the token's team case orbits.IsTokenRefused(err): // a read-only token, or something no token can do case err != nil: if e, ok := orbits.AsError(err); ok { log.Printf("%s (request %s)", e.Detail, e.RequestID) } } ``` Also `IsValidation`, `IsRateLimited`, `IsForbidden`, `IsConflict`, `IsUnauthorized`, `IsPlanRequired`, `IsServerError` and `IsCode(err, "upload_incomplete")`. [Errors](https://docs.orbits.africa/api/errors). ## Pages Paginated lists have a `List` that returns one page, with its `NextCursor`, and an `All` iterator over every item: ```go params := &orbits.ListDeploymentsParams{Environment: orbits.DeploymentEnvironmentProduction} for d, err := range c.Deployments.All(ctx, "my-team", "my-app", params) { if err != nil { return err } fmt.Println(d.ID, d.State) } ``` ## Waiting ```go op, err := c.Projects.Delete(ctx, "my-team", "old-site") if err != nil { return err } _, err = c.Operations.Wait(ctx, op.ID, &orbits.WaitOptions{Timeout: 5 * time.Minute}) // *orbits.OperationError if it failed _, err = c.Deployments.Wait(ctx, "my-team", "my-app", "dpl_…", &orbits.WaitOptions{Interval: 3 * time.Second}) ``` `Operations.Wait` polls an operation until it succeeds, and `Deployments.Wait` a deployment until it is ready. Both poll every 2 seconds unless `Interval` says otherwise. `Timeout` bounds the wait; with none, only `ctx` does. A failed or canceled deployment is a `*orbits.DeploymentError`, whose `Deployment.Failure` says why. ## Idempotency and retries Every `POST` carries an `Idempotency-Key` that its retries reuse, so a retry never makes a change twice. Connection errors and `429`, `502`, `503` and `504` are retried up to three times, with a growing, random wait, or after `Retry-After` when the API sends one. `GET`, `PUT`, `DELETE` and `POST` are retried; a `PATCH` only on `429`, which the API answers before doing anything. ## Calling any endpoint For anything the typed methods don't cover, `Do` sends a raw call with the same auth, retries and errors: ```go var out map[string]any err := c.Do(ctx, "GET", "/teams/my-team/projects", url.Values{"q": {"shop"}}, nil, &out) ``` --- # Getting help Source: https://docs.orbits.africa/help/support Where to look when something isn't working, how to check whether Orbits itself is having a problem, and how to contact the team behind Orbits. ## Look here first Most problems leave a trace you can read yourself. | Something's wrong with | Look at | | --- | --- | | A deploy that failed | The deployment's page and its build log. It says which step failed and why. See [deployments](https://docs.orbits.africa/deploy/deployments) | | A site that built but shows a blank page | The deployment's warnings: Orbits flags public variables the build never had, and pages that threw errors as they loaded | | An app that errors or is slow | [Runtime logs](https://docs.orbits.africa/observe/runtime-logs) (filter on **Error**, or status `5xx`) and [Observability](https://docs.orbits.africa/observe/observability) | | A domain that won't verify or has no certificate | The domain's page says what record it needs and what Orbits found. See [custom domains](https://docs.orbits.africa/domains/custom-domains) | | An error from the API or CLI | The problem's `detail`, and [API › Errors](https://docs.orbits.africa/api/errors). Quote its `request_id` if you contact support | | A `402` | That feature is part of [Pro](https://docs.orbits.africa/billing/plans) | | A `403` on one team only | That team's [security rules](https://docs.orbits.africa/team/security): two-factor, sign-in method or session length | | An API token refused | [When a token stops working](https://docs.orbits.africa/team/api-tokens#when-a-token-stops-working) | | An AI app that can't reach Orbits | [AI troubleshooting](https://docs.orbits.africa/ai/troubleshooting) | ## Is Orbits down? The status page reports how the platform is doing: **[status.pantechdynamics.com](https://status.pantechdynamics.com)**. It's also under **Platform status** in the web app's help menu, the **(i)** in the top bar. The status page is a separate site, so it answers even when the web app doesn't. Orbits is a Pantech Dynamics product, which is why the status page and the contact page are on Pantech's site. ## Contact us Reach the team through **[pantechdynamics.com/contact](https://pantechdynamics.com/contact)**. Tell us: - your team's URL (`orbits.africa/`) and the project; - a link to the deployment, if it's about one; - what you expected and what happened instead; - the `request_id` from an API error, and the time it happened. Never send an API token, a recovery code or an environment variable's value. :::info[In-app support requests] The web app's help menu has **Contact support** and **Send feedback** forms, but sending support requests and feedback from inside Orbits isn't available yet. Use the contact page for now. ::: ## Security problems If you think you've found a security problem in Orbits, contact us through the same page and say it's about security. Don't test it against other people's projects. See [security and privacy](https://docs.orbits.africa/help/security-and-privacy). ## Billing questions For a payment that went through but didn't make the team Pro, wait a few minutes first: a bank transfer can take a while to arrive, and the team becomes Pro when it does. If it still hasn't after that, contact us with the team's URL and the payment's reference from Flutterwave's receipt. See [paying for Pro](https://docs.orbits.africa/billing/paying). --- # Security and privacy Source: https://docs.orbits.africa/help/security-and-privacy Where your apps and data live, how builds and apps are kept apart, how secrets, tokens and payments are protected, and what Orbits keeps about your visitors. ## Where your data lives Orbits runs in one region: **Abuja, Nigeria** (`abj-1`). Your builds, your running apps, your static sites, their logs and your team's data are all kept there. There is no other region to choose. ## Your code is kept apart Orbits treats every customer's code, build steps included, as untrusted: - **Builds run isolated.** A build runs in a sandbox of its own, as an unprivileged user, with no access to Orbits' credentials and no way to reach Orbits' own systems. It can reach the internet, to download packages. - **Apps run isolated too.** A running app can reach the internet (to call your database or another API), but not Orbits' own systems. - **What builds leave behind is checked.** Cached files coming back from storage are only unpacked as plain files and folders, with their paths and sizes checked. - **The workflows endpoint is off the internet.** `/.well-known/orbits/workflows` is blocked on every address, and each call to it carries a per-deployment key. See [workflows](https://docs.orbits.africa/features/workflows). ## Secrets - **Environment variable values are encrypted** before they're stored, with a key kept apart from the data. A variable marked **sensitive** is write-only: no screen, API call or `orbits env pull` ever returns it. Revealing a readable one is a line in the [activity feed](https://docs.orbits.africa/team/activity), which names the key, never the value. See [environment variables](https://docs.orbits.africa/deploy/environment-variables). - **Credentials Orbits holds for you are encrypted the same way**: a GitLab or Bitbucket connection, a Slack connection, a Microsoft Teams workflow address, webhook signing secrets, your two-factor secret. - **When Orbits clones your repository from GitHub**, it uses a short-lived credential limited to that one repository, with read access only. - **Nothing secret is written to logs** by Orbits. What your own app prints is kept as printed, so don't print secrets. ## Tokens and passwords Orbits signs you in without passwords: by a sign-in link sent to your email, or with GitHub, GitLab or Bitbucket. - **Sessions, sign-in links, API tokens, invite links and recovery codes are stored only as hashes.** Orbits can check one, but can't show it again or hand it to anyone. That's why an API token and your recovery codes are shown once. - **[Two-factor](https://docs.orbits.africa/team/security)** with an authenticator app, and ten one-time recovery codes. - **[Team security rules](https://docs.orbits.africa/team/security#team-security-rules)**: owners and admins can require two-factor, limit sign-in methods, sign people out after a set time and choose who can invite. - **[API tokens](https://docs.orbits.africa/team/api-tokens)** reach one team, can be limited to one project and to reading, expire if you choose, and can never manage tokens, members, security rules or billing. - **Someone outside a team** gets "not found" for anything of that team's, so a team's projects and names aren't given away. ## Payments You pay for Pro on **Flutterwave's** hosted page. Card and bank details are typed there only: **Orbits never sees or stores a card number**. It keeps the card's brand, last four digits and expiry, and a token from Flutterwave for renewals. A payment counts only once Orbits has checked it with Flutterwave for the right amount. See [paying for Pro](https://docs.orbits.africa/billing/paying). Invoices hold the payer's email address and are kept for good, as the record of money taken. ## Previews Production is public. Previews can be protected, from the project's settings: - **With a password.** Visitors see a password page; a right password is remembered for 12 hours, and changing the password asks everyone again. - **Team members only.** Visitors are sent to sign in to Orbits, and only members of the project's team get through. Protection is checked on every request to a preview. See [previews](https://docs.orbits.africa/deploy/previews). ## Your visitors **Runtime logs** keep what you need to debug, not more: query strings are never stored, visitors' IP addresses are masked, cookies and `authorization` headers are never read, and only a few request headers are kept. Logs are deleted after 7 days. See [runtime logs](https://docs.orbits.africa/observe/runtime-logs#what-is-and-isnt-stored). **Analytics and Speed Insights** use no cookies and store no IP addresses or browser strings. A visitor is a hash that changes every day, so nobody can be followed from one day to the next or across projects. See [Analytics](https://docs.orbits.africa/observe/analytics#privacy-what-is-collected). **Feature flags** report which ids were checked as the first 16 characters of their SHA-256, never as they were. See [feature flags](https://docs.orbits.africa/features/flags). ## What Orbits sends out - **Webhooks** (alerts and integrations) go only to `https` addresses on the public internet, don't follow redirects, and are signed with your secret, so you can check they came from Orbits. See [integrations](https://docs.orbits.africa/team/integrations#verify-the-signature). - **Slack** gets permission to post and to list channels. It can't read your messages. - **Email** goes to the team's owners, admins and members for the events the team turned on. See [notifications](https://docs.orbits.africa/team/notifications). ## When you delete things - **Deleting a project** deletes its deployments, environment variables and alerts. - **Deleting a team** disconnects its Git providers first, then deletes its domains, projects, activity, members and invites. A Pro plan ends with it. See [deleting a team](https://docs.orbits.africa/team/teams-and-roles#delete-a-team). - **A deleted environment variable** can be restored for 10 minutes, then it's gone. ## Reporting a problem If you think you've found a security problem, contact us through [pantechdynamics.com/contact](https://pantechdynamics.com/contact) and say it's about security. See [getting help](https://docs.orbits.africa/help/support).