API reference · DeployDeployments
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.
The deployment object
Fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Deployments across the team's projects
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.cursorstringqstringMatches the commit message, branch, sha or author.
projectstringProject slug or
prj_id.environmentstringOne of
production,preview.statestringOne of
queued,building,ready,failed,canceled.authorstringAn
authors[].name.
Response 200
Deployments, newest first.itemsarray of DeploymentrequiredShow 23 child fieldsHide child fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
totalintegerrequiredthis_weekintegerrequiredDeployments created since Monday (UTC).
projectsarray of DeploymentProjectrequiredProjects that have deployments, for the Project filter.
Show 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
authorsarray of objectrequiredCommit authors, for the Author filter.
Show 1 child fieldsHide child fields
namestringrequired
next_cursorstring or nullrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/deployments" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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
}A project's 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.cursorstringqstringMatches the commit message, branch, sha or author.
environmentstringOne of
production,preview.statestringOne of
queued,building,ready,failed,canceled.branchstringlivebooleanOnly deployments that have served production.
Response 200
Deployments, newest first.itemsarray of DeploymentrequiredShow 23 child fieldsHide child fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
totalintegerrequiredDeployments that match the filters.
allintegerrequiredEvery deployment of the project, filters aside.
branchesarray of stringrequiredBranches that have deployments, most recent first.
currentnull or DeploymentrequiredWhat production serves; what the inspector shows when nothing is picked.
Show 23 child fieldsHide child fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
auto_deploy_pausedbooleanrequiredTrue after a rollback, until a promote or
POST .../productionlifts it.domainsarray of ProjectDomainrequiredWhat production answers on, once it has a deployment: the team's domains serving the project's production (working ones first, not a branch's or a redirect), then its free address.
Show 3 child fieldsHide child fields
namestringrequiredstatestringrequiredOne of
valid,pending,misconfigured.custombooleanrequired
buildingbooleanrequiredSomething is queued or building.
next_cursorstring or nullrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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
}Deploy a branch now
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonbranchstringAt most 255 characters.
Response 202
Queued.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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"
}'{
"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
}
]
}Start dropping a site or app
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonsizeintegerrequiredThe zip's size in bytes. The URL accepts a file of exactly this length.
From 1 to 104857600.
filenamestringShown as the deployment's message, e.g.
Uploaded site.zip.At most 255 characters.
Response 201
A URL to send the zip to.idstringrequiredPass it to
.../uploads/{upload}/complete.methodstringrequiredAlways
PUT.urlstringrequiredA presigned storage URL. Treat it as a secret until it is used; it expires.
headersobjectrequiredSend exactly these headers with the file, and none besides (they are covered by the signature).
expires_atstringrequiredmax_bytesintegerrequiredThe largest zip accepted.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409
not_an_upload_project(the project deploys from Git) ortoo_many_uploads(finish or cancel the others). - 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
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
}'{
"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
}Deploy a dropped archive
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 <filename>). 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.uploadstringrequiredThe
idfromPOST .../uploads.
Response 202
The deployment, queued.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409
upload_incomplete(not arrived yet) orupload_expired(start again). - 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
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)"{
"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
}
]
}Cancel a drop
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.uploadstringrequiredThe
idfromPOST .../uploads.
Response 204
Cancelled. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads/upl_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"Set what production serves
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsondeployment_idstringrequiredauto_deploy_pausedbooleanrequired
Response 200
Production now serves it.deploymentDeploymentrequiredShow 23 child fieldsHide child fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
auto_deploy_pausedbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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
}'{
"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
}A deployment and its build steps
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Response 200
The deployment.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
frameworkstring or nullrequiredAs the builder detected it.
regionstringrequireddomainsarray of ProjectDomainrequiredProduction's domains, when this is what they serve; otherwise empty. The team's domains serving the project's production (working ones first), then its free address.
Show 3 child fieldsHide child fields
namestringrequiredstatestringrequiredOne of
valid,pending,misconfigured.custombooleanrequired
stepsarray of DeploymentSteprequiredShow 5 child fieldsHide child fields
keystringrequiredThe build log's fixed steps, in order. The screens label them Queued, Cloning repository, Installing packages, Building, Uploading and Going live.
One of
queued,cloning,installing,building,uploading,going_live.statestringrequiredOne of
pending,running,done,failed,skipped.started_atstring or nullrequiredfinished_atstring or nullrequiredsecondsinteger or nullrequiredNull until the step ends.
failurenull or DeploymentFailurerequiredShow 4 child fieldsHide child fields
titlestringrequiredmessagestringrequiredstepstringrequiredThe build log's fixed steps, in order. The screens label them Queued, Cloning repository, Installing packages, Building, Uploading and Going live.
One of
queued,cloning,installing,building,uploading,going_live.lineinteger or nullrequiredThe log line
nthat "Jump to error" scrolls to.
log_linesintegerrequiredHow many log lines the build has.
open_graphnull or DeploymentOpenGraphrequiredThe home page's link-preview tags. Null until the builder has read them (a second or two after the deployment is ready), for a worker, and when the page could not be read (it answered an error, or redirected to another host).
Show 12 child fieldsHide child fields
titlestring or nullrequiredog:title, else<title>.descriptionstring or nullrequiredog:description, else<meta name="description">.imagestring or nullrequiredog:image(orog:image:url,og:image:secure_url). The dashboard loads it from its host; the API does not fetch it.image_was_relativebooleanrequiredThe page wrote
og:imageas a relative URL. Some link bots don't resolve it, so the image may not show.urlstring or nullrequiredog:url, else<link rel="canonical">.site_namestring or nullrequiredog:site_name.twitter_cardstring or nullrequiredtwitter:cardas written (summary,summary_large_image, …). Null means X shows a small summary card.twitter_titlestring or nullrequiredtwitter:title; X uses it overtitle.twitter_descriptionstring or nullrequiredtwitter:description; X uses it overdescription.twitter_imagestring or nullrequiredtwitter:image; X uses it overimage.faviconstring or nullrequired<link rel="icon">. Null when the page declares none; most sites still serve/favicon.ico.fetched_atstringrequiredWhen the builder read the page.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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"
}
}Build log lines
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Query parameters
afterintegerReturn lines after this
n.At least 0. Defaults to
0.limitintegerFrom 1 to 2000. Defaults to
500.
Response 200
Log lines.itemsarray of DeploymentLogLinerequiredShow 5 child fieldsHide child fields
nintegerrequiredLine number, from 1.
atstringrequiredstepstringrequiredThe build log's fixed steps, in order. The screens label them Queued, Cloning repository, Installing packages, Building, Uploading and Going live.
One of
queued,cloning,installing,building,uploading,going_live.tonestringrequiredGreen for success lines, red for errors.
One of
plain,good,bad.textstringrequired
next_afterintegerrequiredSend as
afterto get the next lines.donebooleanrequiredThe build has finished and every line has been returned.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"items": [
{
"n": 1,
"at": "2026-11-10T09:30:00Z",
"step": "queued",
"tone": "plain",
"text": "text"
}
],
"next_after": 1,
"done": false
}Follow a build live (server-sent events)
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(itsidis the line'sn):{"n", "at", "step", "tone", "text"}, oldest first.steps: the six steps, as in the deployment'ssteps, 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'sscreenshot_urlgives. The builder takes the screenshot a few seconds after the deployment is ready, so afterdonethe 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-alivecomment 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).
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Query parameters
afterintegerThe same as Last-Event-ID, for a first connection that already has lines.
At least 0. Defaults to
0.
Response 200 · each event's data
The event stream.No fields.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -N "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs/stream" \
-H "Authorization: Bearer $ORBITS_TOKEN"A deployment's 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Response 200
The JPEG. The body is image/jpeg.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/screenshot" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-o screenshot.jpgBuild the same commit again
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Body
application/jsonuse_cachebooleanDefaults to
true.
Response 202
The new deployment, queued.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
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
}'{
"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
}
]
}Promote to production
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Response 202
The new production deployment, queued.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
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)"{
"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
}
]
}Roll production back
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Response 200
Production now serves it, and auto-deploy is paused.deploymentDeploymentrequiredShow 23 child fieldsHide child fields
idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
auto_deploy_pausedbooleanrequiredundoobjectrequiredSend as the body of
POST .../projects/{project}/productionto undo.Show 2 child fieldsHide child fields
deployment_idstring or nullrequiredauto_deploy_pausedbooleanrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
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)"{
"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
}
}Cancel a build
"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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.deploymentstringrequired
Response 202
Canceled, or being stopped.idstringrequiredprojectDeploymentProjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
environmentstringrequiredWhere a deployment runs.
developmentis only the localorbits devtarget and an environment-variable scope.One of
production,preview.statestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.triggerstringrequiredgita push,manualdeployed by hand,redeploy,promote,createthe first deploy of a new project.One of
git,manual,redeploy,promote,create.branchstringrequiredshastring or nullrequiredThe full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
messagestring or nullrequiredThe commit message's first line.
authornull or objectrequiredShow 1 child fieldsHide child fields
namestringrequired
created_bynull or objectrequiredWho asked for it; null for a push.
Show 2 child fieldsHide child fields
idstringrequirednamestringrequired
urlstring or nullrequiredThis deployment's own address,
https://<slug>-<sha7>.<domain>; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.currentbooleanrequiredProduction serves it now.
went_livebooleanrequiredProduction served it at some point.
redeploy_ofstring or nullrequiredThe commit sha a redeploy rebuilt.
promoted_fromstring or nullrequiredThe
dpl_id of the deployment a promote rebuilt.pull_requestinteger or nullrequiredThe open pull request of the branch, for a preview.
use_cachebooleanrequiredcreated_atstringrequiredstarted_atstring or nullrequiredfinished_atstring or nullrequiredduration_secondsinteger or nullrequiredFrom start to finish; null while it runs (count up from
started_at).screenshot_urlstring or nullrequiredAPI 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.warningsarray of DeploymentWarningrequiredWhat 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.envor.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.Show 5 child fieldsHide child fields
kindstringrequiredOne of
missing_env,page.messagestringrequiredkeysarray of stringmissing_env: the variable names, sorted.errorsarray of stringpage: the uncaught errors, first three.blankbooleanpage: the first screen had nothing on it.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
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)"{
"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
}
]
}