OrbitsDocs
esc
    Open Orbits
    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

    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: 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.

    GET/v1/teams/{team}/deployments
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Query parameters

    • limitinteger

      From 1 to 100. Defaults to 25.

    • cursorstring
    • qstring

      Matches the commit message, branch, sha or author.

    • projectstring

      Project slug or prj_ id.

    • environmentstring

      One of production, preview.

    • statestring

      One of queued, building, ready, failed, canceled.

    • authorstring

      An authors[].name.

    Response 200

    Deployments, newest first.
    • itemsarray of Deploymentrequired
      Show 23 child fields
      • idstringrequired
      • projectDeploymentProjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • environmentstringrequired

        Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

        One of production, preview.

      • statestringrequired

        queued waits for a builder; the screens show it as building.

        One of queued, building, ready, failed, canceled.

      • triggerstringrequired

        git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

        One of git, manual, redeploy, promote, create.

      • branchstringrequired
      • shastring or nullrequired

        The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

      • messagestring or nullrequired

        The commit message's first line.

      • authornull or objectrequired
        Show 1 child fields
        • namestringrequired
      • created_bynull or objectrequired

        Who asked for it; null for a push.

        Show 2 child fields
        • idstringrequired
        • namestringrequired
      • urlstring or nullrequired

        This 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.

      • currentbooleanrequired

        Production serves it now.

      • went_livebooleanrequired

        Production served it at some point.

      • redeploy_ofstring or nullrequired

        The commit sha a redeploy rebuilt.

      • promoted_fromstring or nullrequired

        The dpl_ id of the deployment a promote rebuilt.

      • pull_requestinteger or nullrequired

        The open pull request of the branch, for a preview.

      • use_cachebooleanrequired
      • created_atstringrequired
      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • duration_secondsinteger or nullrequired

        From start to finish; null while it runs (count up from started_at).

      • screenshot_urlstring or nullrequired

        API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

      • warningsarray of DeploymentWarningrequired

        What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

        Show 5 child fields
        • kindstringrequired

          One of missing_env, page.

        • messagestringrequired
        • keysarray of string

          missing_env: the variable names, sorted.

        • errorsarray of string

          page: the uncaught errors, first three.

        • blankboolean

          page: the first screen had nothing on it.

    • totalintegerrequired
    • this_weekintegerrequired

      Deployments created since Monday (UTC).

    • projectsarray of DeploymentProjectrequired

      Projects that have deployments, for the Project filter.

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • authorsarray of objectrequired

      Commit authors, for the Author filter.

      Show 1 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"
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/deployments
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • limitinteger

      From 1 to 100. Defaults to 25.

    • cursorstring
    • qstring

      Matches the commit message, branch, sha or author.

    • environmentstring

      One of production, preview.

    • statestring

      One of queued, building, ready, failed, canceled.

    • branchstring
    • liveboolean

      Only deployments that have served production.

    Response 200

    Deployments, newest first.
    • itemsarray of Deploymentrequired
      Show 23 child fields
      • idstringrequired
      • projectDeploymentProjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • environmentstringrequired

        Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

        One of production, preview.

      • statestringrequired

        queued waits for a builder; the screens show it as building.

        One of queued, building, ready, failed, canceled.

      • triggerstringrequired

        git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

        One of git, manual, redeploy, promote, create.

      • branchstringrequired
      • shastring or nullrequired

        The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

      • messagestring or nullrequired

        The commit message's first line.

      • authornull or objectrequired
        Show 1 child fields
        • namestringrequired
      • created_bynull or objectrequired

        Who asked for it; null for a push.

        Show 2 child fields
        • idstringrequired
        • namestringrequired
      • urlstring or nullrequired

        This 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.

      • currentbooleanrequired

        Production serves it now.

      • went_livebooleanrequired

        Production served it at some point.

      • redeploy_ofstring or nullrequired

        The commit sha a redeploy rebuilt.

      • promoted_fromstring or nullrequired

        The dpl_ id of the deployment a promote rebuilt.

      • pull_requestinteger or nullrequired

        The open pull request of the branch, for a preview.

      • use_cachebooleanrequired
      • created_atstringrequired
      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • duration_secondsinteger or nullrequired

        From start to finish; null while it runs (count up from started_at).

      • screenshot_urlstring or nullrequired

        API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

      • warningsarray of DeploymentWarningrequired

        What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

        Show 5 child fields
        • kindstringrequired

          One of missing_env, page.

        • messagestringrequired
        • keysarray of string

          missing_env: the variable names, sorted.

        • errorsarray of string

          page: the uncaught errors, first three.

        • blankboolean

          page: the first screen had nothing on it.

    • totalintegerrequired

      Deployments that match the filters.

    • allintegerrequired

      Every deployment of the project, filters aside.

    • branchesarray of stringrequired

      Branches that have deployments, most recent first.

    • currentnull or Deploymentrequired

      What production serves; what the inspector shows when nothing is picked.

      Show 23 child fields
      • idstringrequired
      • projectDeploymentProjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • environmentstringrequired

        Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

        One of production, preview.

      • statestringrequired

        queued waits for a builder; the screens show it as building.

        One of queued, building, ready, failed, canceled.

      • triggerstringrequired

        git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

        One of git, manual, redeploy, promote, create.

      • branchstringrequired
      • shastring or nullrequired

        The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

      • messagestring or nullrequired

        The commit message's first line.

      • authornull or objectrequired
        Show 1 child fields
        • namestringrequired
      • created_bynull or objectrequired

        Who asked for it; null for a push.

        Show 2 child fields
        • idstringrequired
        • namestringrequired
      • urlstring or nullrequired

        This 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.

      • currentbooleanrequired

        Production serves it now.

      • went_livebooleanrequired

        Production served it at some point.

      • redeploy_ofstring or nullrequired

        The commit sha a redeploy rebuilt.

      • promoted_fromstring or nullrequired

        The dpl_ id of the deployment a promote rebuilt.

      • pull_requestinteger or nullrequired

        The open pull request of the branch, for a preview.

      • use_cachebooleanrequired
      • created_atstringrequired
      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • duration_secondsinteger or nullrequired

        From start to finish; null while it runs (count up from started_at).

      • screenshot_urlstring or nullrequired

        API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

      • warningsarray of DeploymentWarningrequired

        What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

        Show 5 child fields
        • kindstringrequired

          One of missing_env, page.

        • messagestringrequired
        • keysarray of string

          missing_env: the variable names, sorted.

        • errorsarray of string

          page: the uncaught errors, first three.

        • blankboolean

          page: the first screen had nothing on it.

    • auto_deploy_pausedbooleanrequired

      True after a rollback, until a promote or POST .../production lifts it.

    • domainsarray of ProjectDomainrequired

      What 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 fields
      • namestringrequired
      • statestringrequired

        One of valid, pending, misconfigured.

      • custombooleanrequired
    • buildingbooleanrequired

      Something 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"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/deployments
    Full tokenNeeds Idempotency-KeyReturns202Accepted

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • branchstring

      At most 255 characters.

    Response 202

    Queued.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: the first screen had nothing on it.

    Errors

    • 402The team's plan doesn't include this (see GET /v1/plans). code is plan_required, required_plan is pro and feature names what is missing; show the upgrade dialog.
    • 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"
      }'
    Response 202
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/uploads
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • sizeintegerrequired

      The zip's size in bytes. The URL accepts a file of exactly this length.

      From 1 to 104857600.

    • filenamestring

      Shown as the deployment's message, e.g. Uploaded site.zip.

      At most 255 characters.

    Response 201

    A URL to send the zip to.
    • idstringrequired

      Pass it to .../uploads/{upload}/complete.

    • methodstringrequired

      Always PUT.

    • urlstringrequired

      A presigned storage URL. Treat it as a secret until it is used; it expires.

    • headersobjectrequired

      Send exactly these headers with the file, and none besides (they are covered by the signature).

    • expires_atstringrequired
    • max_bytesintegerrequired

      The 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).
    • 409not_an_upload_project (the project deploys from Git) or too_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
      }'
    Response 201
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/uploads/{upload}/complete
    Full tokenNeeds Idempotency-KeyReturns202Accepted

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • uploadstringrequired

      The id from POST .../uploads.

    Response 202

    The deployment, queued.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: the first screen had nothing on it.

    Errors

    • 402The team's plan doesn't include this (see GET /v1/plans). code is plan_required, required_plan is pro and feature names what is missing; show the upgrade dialog.
    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409upload_incomplete (not arrived yet) or upload_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)"
    Response 202
    {
      "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.

    DELETE/v1/teams/{team}/projects/{project}/uploads/{upload}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • uploadstringrequired

      The id from POST .../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"
    HTTP/1.1 204 No Content

    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.

    POST/v1/teams/{team}/projects/{project}/production
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • deployment_idstringrequired
    • auto_deploy_pausedbooleanrequired

    Response 200

    Production now serves it.
    • deploymentDeploymentrequired
      Show 23 child fields
      • idstringrequired
      • projectDeploymentProjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • environmentstringrequired

        Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

        One of production, preview.

      • statestringrequired

        queued waits for a builder; the screens show it as building.

        One of queued, building, ready, failed, canceled.

      • triggerstringrequired

        git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

        One of git, manual, redeploy, promote, create.

      • branchstringrequired
      • shastring or nullrequired

        The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

      • messagestring or nullrequired

        The commit message's first line.

      • authornull or objectrequired
        Show 1 child fields
        • namestringrequired
      • created_bynull or objectrequired

        Who asked for it; null for a push.

        Show 2 child fields
        • idstringrequired
        • namestringrequired
      • urlstring or nullrequired

        This 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.

      • currentbooleanrequired

        Production serves it now.

      • went_livebooleanrequired

        Production served it at some point.

      • redeploy_ofstring or nullrequired

        The commit sha a redeploy rebuilt.

      • promoted_fromstring or nullrequired

        The dpl_ id of the deployment a promote rebuilt.

      • pull_requestinteger or nullrequired

        The open pull request of the branch, for a preview.

      • use_cachebooleanrequired
      • created_atstringrequired
      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • duration_secondsinteger or nullrequired

        From start to finish; null while it runs (count up from started_at).

      • screenshot_urlstring or nullrequired

        API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

      • warningsarray of DeploymentWarningrequired

        What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

        Show 5 child fields
        • kindstringrequired

          One of missing_env, page.

        • messagestringrequired
        • keysarray of string

          missing_env: the variable names, sorted.

        • errorsarray of string

          page: the uncaught errors, first three.

        • blankboolean

          page: 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
      }'
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/deployments/{deployment}
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Response 200

    The deployment.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: the first screen had nothing on it.

    • frameworkstring or nullrequired

      As the builder detected it.

    • regionstringrequired
    • domainsarray of ProjectDomainrequired

      Production'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 fields
      • namestringrequired
      • statestringrequired

        One of valid, pending, misconfigured.

      • custombooleanrequired
    • stepsarray of DeploymentSteprequired
      Show 5 child fields
      • keystringrequired

        The 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.

      • statestringrequired

        One of pending, running, done, failed, skipped.

      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • secondsinteger or nullrequired

        Null until the step ends.

    • failurenull or DeploymentFailurerequired
      Show 4 child fields
      • titlestringrequired
      • messagestringrequired
      • stepstringrequired

        The 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 nullrequired

        The log line n that "Jump to error" scrolls to.

    • log_linesintegerrequired

      How many log lines the build has.

    • open_graphnull or DeploymentOpenGraphrequired

      The 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 fields
      • titlestring or nullrequired

        og:title, else <title>.

      • descriptionstring or nullrequired

        og:description, else <meta name="description">.

      • imagestring or nullrequired

        og:image (or og:image:url, og:image:secure_url). The dashboard loads it from its host; the API does not fetch it.

      • image_was_relativebooleanrequired

        The page wrote og:image as a relative URL. Some link bots don't resolve it, so the image may not show.

      • urlstring or nullrequired

        og:url, else <link rel="canonical">.

      • site_namestring or nullrequired

        og:site_name.

      • twitter_cardstring or nullrequired

        twitter:card as written (summary, summary_large_image, …). Null means X shows a small summary card.

      • twitter_titlestring or nullrequired

        twitter:title; X uses it over title.

      • twitter_descriptionstring or nullrequired

        twitter:description; X uses it over description.

      • twitter_imagestring or nullrequired

        twitter:image; X uses it over image.

      • faviconstring or nullrequired

        <link rel="icon">. Null when the page declares none; most sites still serve /favicon.ico.

      • fetched_atstringrequired

        When 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"
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/deployments/{deployment}/logs
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Query parameters

    • afterinteger

      Return lines after this n.

      At least 0. Defaults to 0.

    • limitinteger

      From 1 to 2000. Defaults to 500.

    Response 200

    Log lines.
    • itemsarray of DeploymentLogLinerequired
      Show 5 child fields
      • nintegerrequired

        Line number, from 1.

      • atstringrequired
      • stepstringrequired

        The 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.

      • tonestringrequired

        Green for success lines, red for errors.

        One of plain, good, bad.

      • textstringrequired
    • next_afterintegerrequired

      Send as after to get the next lines.

    • donebooleanrequired

      The 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"
    Response 200
    {
      "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 (its id is the line's n): {"n", "at", "step", "tone", "text"}, oldest first.
    • steps: the six steps, as in the deployment's steps, whenever one changes.
    • done: {"state", "failure", "duration_seconds"} once the build has ended and every line has been sent. The stream then closes, unless the deployment just went ready.
    • screenshot: {"screenshot_url"}, the same URL the deployment's screenshot_url gives. The builder takes the screenshot a few seconds after the deployment is ready, so after done the stream stays open for up to 2 minutes and sends this when it is saved, then closes. Refresh the deployment (or its thumbnail) on it. It is not sent for a failed or canceled build, a worker, a deployment that already had its screenshot, or one that finished more than 2 minutes ago.
    • A : keep-alive comment every 15 s while nothing happens.

    The stream closes after 30 minutes or when a proxy cuts it (staging's after 5); reconnect with Last-Event-ID set to the last line id received (EventSource does this by itself) and it carries on with the next line, without gaps or repeats. A finished deployment answers with any remaining lines, its steps and done at once.

    Permissions: Any team member. A non-member gets 404 (a problem document, not a stream).

    GET/v1/teams/{team}/projects/{project}/deployments/{deployment}/logs/stream
    Read or full tokenServer-Sent EventsReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Query parameters

    • afterinteger

      The 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"
    HTTP/1.1 200

    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.

    GET/v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project 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.jpg
    HTTP/1.1 200

    Build 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.

    POST/v1/teams/{team}/projects/{project}/deployments/{deployment}/redeploy
    Full tokenNeeds Idempotency-KeyReturns202Accepted

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Body

    application/json
    • use_cacheboolean

      Defaults to true.

    Response 202

    The new deployment, queued.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: the first screen had nothing on it.

    Errors

    • 402The team's plan doesn't include this (see GET /v1/plans). code is plan_required, required_plan is pro and feature names what is missing; show the upgrade dialog.
    • 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
      }'
    Response 202
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/deployments/{deployment}/promote
    Full tokenNeeds Idempotency-KeyReturns202Accepted

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Response 202

    The new production deployment, queued.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: the first screen had nothing on it.

    Errors

    • 402The team's plan doesn't include this (see GET /v1/plans). code is plan_required, required_plan is pro and feature names what is missing; show the upgrade dialog.
    • 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)"
    Response 202
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/deployments/{deployment}/rollback
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Response 200

    Production now serves it, and auto-deploy is paused.
    • deploymentDeploymentrequired
      Show 23 child fields
      • idstringrequired
      • projectDeploymentProjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • environmentstringrequired

        Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

        One of production, preview.

      • statestringrequired

        queued waits for a builder; the screens show it as building.

        One of queued, building, ready, failed, canceled.

      • triggerstringrequired

        git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

        One of git, manual, redeploy, promote, create.

      • branchstringrequired
      • shastring or nullrequired

        The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

      • messagestring or nullrequired

        The commit message's first line.

      • authornull or objectrequired
        Show 1 child fields
        • namestringrequired
      • created_bynull or objectrequired

        Who asked for it; null for a push.

        Show 2 child fields
        • idstringrequired
        • namestringrequired
      • urlstring or nullrequired

        This 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.

      • currentbooleanrequired

        Production serves it now.

      • went_livebooleanrequired

        Production served it at some point.

      • redeploy_ofstring or nullrequired

        The commit sha a redeploy rebuilt.

      • promoted_fromstring or nullrequired

        The dpl_ id of the deployment a promote rebuilt.

      • pull_requestinteger or nullrequired

        The open pull request of the branch, for a preview.

      • use_cachebooleanrequired
      • created_atstringrequired
      • started_atstring or nullrequired
      • finished_atstring or nullrequired
      • duration_secondsinteger or nullrequired

        From start to finish; null while it runs (count up from started_at).

      • screenshot_urlstring or nullrequired

        API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

      • warningsarray of DeploymentWarningrequired

        What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

        Show 5 child fields
        • kindstringrequired

          One of missing_env, page.

        • messagestringrequired
        • keysarray of string

          missing_env: the variable names, sorted.

        • errorsarray of string

          page: the uncaught errors, first three.

        • blankboolean

          page: the first screen had nothing on it.

    • auto_deploy_pausedbooleanrequired
    • undoobjectrequired

      Send as the body of POST .../projects/{project}/production to undo.

      Show 2 child fields
      • deployment_idstring or nullrequired
      • 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.

    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)"
    Response 200
    {
      "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.

    POST/v1/teams/{team}/projects/{project}/deployments/{deployment}/cancel
    Full tokenNeeds Idempotency-KeyReturns202Accepted

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A 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

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • deploymentstringrequired

    Response 202

    Canceled, or being stopped.
    • idstringrequired
    • projectDeploymentProjectrequired
      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • environmentstringrequired

      Where a deployment runs. development is only the local orbits dev target and an environment-variable scope.

      One of production, preview.

    • statestringrequired

      queued waits for a builder; the screens show it as building.

      One of queued, building, ready, failed, canceled.

    • triggerstringrequired

      git a push, manual deployed by hand, redeploy, promote, create the first deploy of a new project.

      One of git, manual, redeploy, promote, create.

    • branchstringrequired
    • shastring or nullrequired

      The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.

    • messagestring or nullrequired

      The commit message's first line.

    • authornull or objectrequired
      Show 1 child fields
      • namestringrequired
    • created_bynull or objectrequired

      Who asked for it; null for a push.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • urlstring or nullrequired

      This 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.

    • currentbooleanrequired

      Production serves it now.

    • went_livebooleanrequired

      Production served it at some point.

    • redeploy_ofstring or nullrequired

      The commit sha a redeploy rebuilt.

    • promoted_fromstring or nullrequired

      The dpl_ id of the deployment a promote rebuilt.

    • pull_requestinteger or nullrequired

      The open pull request of the branch, for a preview.

    • use_cachebooleanrequired
    • created_atstringrequired
    • started_atstring or nullrequired
    • finished_atstring or nullrequired
    • duration_secondsinteger or nullrequired

      From start to finish; null while it runs (count up from started_at).

    • screenshot_urlstring or nullrequired

      API path of the deployment's first screen (1280x800 JPEG), GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.

    • warningsarray of DeploymentWarningrequired

      What this deployment may be missing, for its page; empty when nothing is. missing_env: public variables the code reads (import.meta.env.VITE_*, process.env.NEXT_PUBLIC_*, REACT_APP_*, PUBLIC_*) that weren't set for this environment, nor in a committed .env or .env.production, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. page: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.

      Show 5 child fields
      • kindstringrequired

        One of missing_env, page.

      • messagestringrequired
      • keysarray of string

        missing_env: the variable names, sorted.

      • errorsarray of string

        page: the uncaught errors, first three.

      • blankboolean

        page: 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)"
    Response 202
    {
      "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
        }
      ]
    }

    Was this page helpful?

    Updated