API reference · DeployProjects
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 <slug>.theorbits.app; renaming a project changes it. {project} in a path is the slug or the prj_ id. See Projects for the guide.
The project object
Fields
idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
Starter templates for a new project
The "Start from a template" catalog on the New project screens, read from 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Response 200
Templates.itemsarray of TemplaterequiredShow 10 child fieldsHide child fields
keystringrequirednamestringrequireddescriptionstringrequiredcategorystringrequiredOne of
commerce,content,apps,apis.frameworkstringrequiredframework_labelstringrequiredrequired_envarray of TemplateEnvVarrequiredVariables the template can't start without; send each in
envwhen creating the project.Show 2 child fieldsHide child fields
keystringrequiredhintstring or null
optional_envarray of TemplateEnvVarrequiredVariables the template reads when they are set.
Show 2 child fieldsHide child fields
keystringrequiredhintstring or null
workloadobjectHow a project from this template runs. Absent means the framework's default.
node_versionstringThe Node.js version a project from this template gets, when it needs newer than the default.
curl "https://api.theorbits.app/v1/templates" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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"
}
]
}List 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.cursorstringqstringsortstringOne of
last_deploy,name,created. Defaults tolast_deploy.repositorystringOnly projects imported from this repository, e.g.
shadyventures/storefront.
Response 200
Projects.next_cursorstring or nullitemsarray of ProjectrequiredShow 22 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
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" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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"
}
]
}Create a project from a repository or a template
Create a project: the Deploy button on the New project > Configure screens.
name becomes the free address, <slug>.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.
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.
Body
application/jsonnamestringrequiredAlso the source of the slug and free address, e.g.
checkout-v2.At most 100 characters.
slugstringworkloadWorkloadShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourceSourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
templatestringTemplate
keyfromGET /v1/templates. Mutually exclusive withsource: Orbits creates the repository in the team's GitHub account.source_kindstringDefault
git.uploadcreates a project with no repository, deployed by dropping files (POST /teams/{team}/projects/{project}/uploads); no deployment is queued until the first drop. Not withsourceortemplate.One of
git,upload.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
regionstringDefaults to
abj-1.envarray of objectEnvironment 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.
Show 4 child fieldsHide child fields
keystringrequiredAt most 255 characters.
valuestringrequiredMay be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on
EnvVar.value.At most 32768 characters.
environmentsarray of stringUsed by Production and Preview unless the user picks otherwise.
sensitivebooleanWrite-only: nobody can read the value back, only replace it.
Defaults to
true.
Response 202
Project created. With asource, its first production deployment is queued too and shows as latest_deployment.idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
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.
- 503The repository could not be verified, or GitHub could not be reached to create one; nothing was created. Retry.
Every code is explained in Errors.
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"
}'{
"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"
}Get a 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The project.idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
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" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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"
}Change project settings
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonnamestringAt most 100 characters.
workloadWorkloadShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourceSourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
gitobjectShow 3 child fieldsHide child fields
deploy_on_pushbooleanpreview_pull_requestsbooleancomment_on_pull_requestsboolean
node_versionstringpreview_protectionstringOne of
none,team_members,password.preview_passwordstringOnly with
preview_protectionpassword.regionstring
Response 200
Updated.idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
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 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"
}'{
"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"
}Delete a 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 202
Deletion accepted.idstringrequiredkindstringrequiredstatestringrequiredOne of
pending,running,succeeded,failed.resourcestringcreated_atstringrequiredfinished_atstring or nullerrornull or ProblemShow 10 child fieldsHide child fields
typestringrequiredtitlestringrequiredstatusintegerrequireddetailstringinstancestringrequest_idstringcodestringA stable reason, where one is defined:
plan_required(402);price_changedandalready_pro(409) andbilling_unavailable(503) from billing.required_planstringOn a 402: the plan that includes what was asked for.
One of
pro.featurestringOn a 402: what the plan lacks.
One of
functions,sandboxes,analytics,speed_insights.errorsarray of objectShow 2 child fieldsHide child fields
fieldstringrequiredmessagestringrequired
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" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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"
}
]
}
}What deleting a project removes
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
Counts of what is removed or detached.deploymentsintegerrequiredDeployments and their build logs.
environment_variablesintegerrequiredflagsintegerrequiredFeature flags and their history.
domainsintegerrequiredDetached, not deleted; they stay in Domains and DNS.
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 "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deletion-impact" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"deployments": 1,
"environment_variables": 1,
"flags": 1,
"domains": 1
}Pause or resume a project
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.
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/jsonpausedbooleanrequired
Response 200
The updated project.idstringrequiredslugstringrequirednamestringrequiredfree_addressstringrequiredHost name,
<slug>.theorbits.app.workloadWorkloadrequiredShow 14 child fieldsHide child fields
typestringrequiredAlways
container.output_directorystringspa_fallbackbooleanDefaults to
false.frameworkstringmemory_mbintegerAt least 128.
timeout_secondsintegerAt least 1.
commandarray of stringreplicasintegerAt least 1. Defaults to
1.schedulestring or nullCron expression for scheduled jobs; null for a continuous worker.
portintegerFrom 1 to 65535.
health_check_pathstringDefaults to
/.start_commandarray of stringimagestring or nullPrebuilt image reference. Mutually exclusive with
dockerfile_path.dockerfile_pathstring or null
sourcenull or SourceShow 4 child fieldsHide child fields
providerstringrequiredOne of
github,gitlab,bitbucket,gitbucket.repositorystringrequiredproduction_branchstringrequiredDefaults to
main.root_directorystringDefaults to
./.
source_kindstringupload: deployed by dropping files (POST .../uploads);sourceis null and there is no repository.One of
git,upload. Defaults togit.buildBuildConfigShow 7 child fieldsHide child fields
frameworkstring or nullinstall_commandstring or nullnull means detected default.
build_commandstring or nulloutput_directorystring or nullignore_commandstring or nullThe 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 seesORBITS_GIT_COMMIT_SHA,ORBITS_GIT_COMMIT_REFandORBITS_ENV, and theirVERCEL_*names. Example:git diff --quiet HEAD^ HEAD -- ./apps/storefront.changed_byobject or nullWho last changed a build setting ("Changed by Tunde Bakare yesterday").
Show 2 child fieldsHide child fields
idstringnamestring
changed_atstring or null
framework_versionstring or nullShown next to the framework on the overview header, e.g.
15.node_versionstringregionstringrequiredstatusstringrequiredWhat the project cards and the project switcher show.
pendingmeans nothing has been deployed yet.building,readyandfailedfollow the latest deployment (a canceled latest one falls back to production:ready, orpendingif nothing served yet).One of
pending,building,ready,failed,paused.pausedbooleangitGitSettingsrequiredShow 3 child fieldsHide child fields
deploy_on_pushbooleanrequiredPushes to the production branch go to production; other branches get a preview.
preview_pull_requestsbooleanrequiredEach pull request gets its own address.
comment_on_pull_requestsbooleanrequiredPost the preview link on the pull request and update it on every push.
preview_protectionstringWho 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 toteam_members.production_urlstring or nulllatest_deployment_idstring or nulllatest_deploymentnull or LatestDeploymentShow 8 child fieldsHide child fields
idstringrequiredstatestringrequiredqueuedwaits for a builder; the screens show it as building.One of
queued,building,ready,failed,canceled.branchstring or nullcommit_shastring or nullcommit_messagestring or nullauthorobject or nullShow 2 child fieldsHide child fields
namestringavatar_urlstring or null
failure_reasonstring or nullcreated_atstringrequired
thumbnail_urlstring or nullAPI path of the screenshot of what production serves, for the project card (the
screenshot_urlof that deployment). Null until production has one. Fetch it with the session, like any API call.thumbnail_colorstring or nullThe 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_atstringrequiredupdated_atstring
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 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
}'{
"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"
}