# Deployments

Start, follow, promote, roll back, redeploy and cancel deployments, upload source, and read build logs.

Source: https://docs.orbits.africa/api/deployments

A deployment is one build of a project, immutable once built. A push to a connected repository creates one by itself; `POST .../deployments` builds a branch's newest commit, and a project with `source_kind: upload` deploys from a zip you upload. Creating one answers `202` with the new deployment: poll it, or follow its build log stream, until its `state` is `ready`, `failed` or `canceled`. Promoting, rolling back and setting production move a pointer. See [Deployments](https://docs.orbits.africa/deploy/deployments).

Endpoints:

- `GET /v1/teams/{team}/deployments`: Deployments across the team's projects
- `GET /v1/teams/{team}/projects/{project}/deployments`: A project's deployments
- `POST /v1/teams/{team}/projects/{project}/deployments`: Deploy a branch now
- `POST /v1/teams/{team}/projects/{project}/uploads`: Start dropping a site or app
- `POST /v1/teams/{team}/projects/{project}/uploads/{upload}/complete`: Deploy a dropped archive
- `DELETE /v1/teams/{team}/projects/{project}/uploads/{upload}`: Cancel a drop
- `POST /v1/teams/{team}/projects/{project}/production`: Set what production serves
- `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}`: A deployment and its build steps
- `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs`: Build log lines
- `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs/stream`: Follow a build live (server-sent events)
- `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot`: A deployment's screenshot
- `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/redeploy`: Build the same commit again
- `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/promote`: Promote to production
- `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/rollback`: Roll production back
- `POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/cancel`: Cancel a build

## The deployment object



- `id` (string, required)
- `project` (DeploymentProject, required)
  - `id` (string, required)
  - `slug` (string, required)
  - `name` (string, required)
- `environment` (string, required): Where a deployment runs. `development` is only the local `orbits dev` target and an environment-variable scope. One of `production`, `preview`.
- `state` (string, required): `queued` waits for a builder; the screens show it as building. One of `queued`, `building`, `ready`, `failed`, `canceled`.
- `trigger` (string, required): `git` a push, `manual` deployed by hand, `redeploy`, `promote`, `create` the first deploy of a new project. One of `git`, `manual`, `redeploy`, `promote`, `create`.
- `branch` (string, required)
- `sha` (string or null, required): The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
- `message` (string or null, required): The commit message's first line.
- `author` (null or object, required)
  - `name` (string, required)
- `created_by` (null or object, required): Who asked for it; null for a push.
  - `id` (string, required)
  - `name` (string, required)
- `url` (string or null, required): This deployment's own address, `https://<slug>-<sha7>.<domain>`; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.
- `current` (boolean, required): Production serves it now.
- `went_live` (boolean, required): Production served it at some point.
- `redeploy_of` (string or null, required): The commit sha a redeploy rebuilt.
- `promoted_from` (string or null, required): The `dpl_` id of the deployment a promote rebuilt.
- `pull_request` (integer or null, required): The open pull request of the branch, for a preview.
- `use_cache` (boolean, required)
- `created_at` (string, required)
- `started_at` (string or null, required)
- `finished_at` (string or null, required)
- `duration_seconds` (integer or null, required): From start to finish; null while it runs (count up from `started_at`).
- `screenshot_url` (string or null, required): API path of the deployment's first screen (1280x800 JPEG), `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot`. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.
- `warnings` (array of DeploymentWarning, required): What this deployment may be missing, for its page; empty when nothing is. `missing_env`: public variables the code reads (`import.meta.env.VITE_*`, `process.env.NEXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`) that weren't set for this environment, nor in a committed `.env` or `.env.production`, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. `page`: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank.
  - `kind` (string, required): One of `missing_env`, `page`.
  - `message` (string, required)
  - `keys` (array of string): `missing_env`: the variable names, sorted.
  - `errors` (array of string): `page`: the uncaught errors, first three.
  - `blank` (boolean): `page`: the first screen had nothing on it.
## Deployments across the team's projects

```http
GET /v1/teams/{team}/deployments
```

The team's Deployments page: every deployment across its projects, newest first, with the facets for its filters (Project, Environment, Status, Author) and "38 this week".

An API token limited to one project may call this too: the deployments, `projects`, `authors`, `total` and `this_week` then cover only that project, and a `project` filter naming another project returns an empty list.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string)
- `q` (string): Matches the commit message, branch, sha or author.
- `project` (string): Project slug or `prj_` id.
- `environment` (string): One of `production`, `preview`.
- `state` (string): One of `queued`, `building`, `ready`, `failed`, `canceled`.
- `author` (string): An `authors[].name`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/deployments" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "project": {
        "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "slug": "my-app",
        "name": "my-app"
      },
      "environment": "production",
      "state": "queued",
      "trigger": "git",
      "branch": "main",
      "sha": null,
      "message": "Update checkout copy",
      "author": {
        "name": "Shady Asaolu"
      },
      "created_by": {
        "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "name": "my-app"
      },
      "url": "https://storefront-a1f9c2e.theorbits.app",
      "current": false,
      "went_live": false,
      "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "pull_request": null,
      "use_cache": false,
      "created_at": "2026-11-10T09:30:00Z",
      "started_at": "2026-11-10T09:30:00Z",
      "finished_at": "2026-11-10T09:30:00Z",
      "duration_seconds": null,
      "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
      "warnings": [
        {
          "kind": "missing_env",
          "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
          "keys": [
            "keys"
          ],
          "errors": [
            "errors"
          ],
          "blank": false
        }
      ]
    }
  ],
  "total": 1,
  "this_week": 1,
  "projects": [
    {
      "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    }
  ],
  "authors": [
    {
      "name": "My Team"
    }
  ],
  "next_cursor": null
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## A project's deployments

```http
GET /v1/teams/{team}/projects/{project}/deployments
```

The project's Deployments page: every build, newest first, with the filters (search, Env, Status, Branch, "Production only") and what the inspector shows when nothing is picked (`current`, the deployment production serves, and its `domains`).

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string)
- `q` (string): Matches the commit message, branch, sha or author.
- `environment` (string): One of `production`, `preview`.
- `state` (string): One of `queued`, `building`, `ready`, `failed`, `canceled`.
- `branch` (string)
- `live` (boolean): Only deployments that have served production.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "project": {
        "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "slug": "my-app",
        "name": "my-app"
      },
      "environment": "production",
      "state": "queued",
      "trigger": "git",
      "branch": "main",
      "sha": null,
      "message": "Update checkout copy",
      "author": {
        "name": "Shady Asaolu"
      },
      "created_by": {
        "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "name": "my-app"
      },
      "url": "https://storefront-a1f9c2e.theorbits.app",
      "current": false,
      "went_live": false,
      "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "pull_request": null,
      "use_cache": false,
      "created_at": "2026-11-10T09:30:00Z",
      "started_at": "2026-11-10T09:30:00Z",
      "finished_at": "2026-11-10T09:30:00Z",
      "duration_seconds": null,
      "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
      "warnings": [
        {
          "kind": "missing_env",
          "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
          "keys": [
            "keys"
          ],
          "errors": [
            "errors"
          ],
          "blank": false
        }
      ]
    }
  ],
  "total": 1,
  "all": 1,
  "branches": [
    "branches"
  ],
  "current": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "project": {
      "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    },
    "environment": "production",
    "state": "queued",
    "trigger": "git",
    "branch": "main",
    "sha": null,
    "message": "Update checkout copy",
    "author": {
      "name": "Shady Asaolu"
    },
    "created_by": {
      "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "my-app"
    },
    "url": "https://storefront-a1f9c2e.theorbits.app",
    "current": false,
    "went_live": false,
    "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "pull_request": null,
    "use_cache": false,
    "created_at": "2026-11-10T09:30:00Z",
    "started_at": "2026-11-10T09:30:00Z",
    "finished_at": "2026-11-10T09:30:00Z",
    "duration_seconds": null,
    "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
    "warnings": [
      {
        "kind": "missing_env",
        "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
        "keys": [
          "keys"
        ],
        "errors": [
          "errors"
        ],
        "blank": false
      }
    ]
  },
  "auto_deploy_paused": false,
  "domains": [
    {
      "name": "storefront.theorbits.app",
      "state": "valid",
      "custom": false
    }
  ],
  "building": false,
  "next_cursor": null
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Deploy a branch now

```http
POST /v1/teams/{team}/projects/{project}/deployments
```

Queues a build of a branch's newest commit, for a deploy started by hand (the CLI's `orbits deploy`). The production branch deploys to production; any other branch to preview. Pushes and the first deploy of a new project are queued by Orbits itself and need no call. Returns at once with the queued deployment; follow it with `GET .../deployments/{deployment}` and its logs.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `branch` (string): At most 255 characters.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main"
  }'
```

Response `202`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ]
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Start dropping a site or app

```http
POST /v1/teams/{team}/projects/{project}/uploads
```

The drag and drop deploy: the person drops a folder (or a `.zip`) on the project, and the browser sends it to storage on a presigned URL, so the files never pass through the API. The archive is the project's **source code**, in place of a Git clone: Orbits unpacks it, detects the framework, installs, builds and publishes or runs it like any other deployment, for any kind of project. Only projects created with `source_kind: upload` take drops.

What goes in the archive: the project's files, with `package.json`, source and config. Anything named `node_modules`, `.git`, `.next`, `__MACOSX` or `.DS_Store`, at any depth, is left out, and a single top-level folder is stripped, so zipping the folder or its contents both work. Limits: the zip may be up to `max_bytes` (100 MiB, 104,857,600 bytes); unpacked it may be up to 500 MiB and 20,000 entries, where the folders the zip lists count as well as its files (what is left out doesn't count); links and special files are refused. The build reports a breach on the Cloning step.

Starting signs a PUT URL for the zip (valid ten minutes). At most 5 unfinished uploads per team.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `size` (integer, required): The zip's size in bytes. The URL accepts a file of exactly this length. From 1 to 104857600.
- `filename` (string): Shown as the deployment's message, e.g. `Uploaded site.zip`. At most 255 characters.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 1
  }'
```

Response `201`:

```json
{
  "id": "upl_0192f3a6-0c1d-7a55-9a52-6f1f0f0f0f0f",
  "method": "PUT",
  "url": "https://my-app.theorbits.app",
  "headers": {},
  "expires_at": "2026-11-10T09:30:00Z",
  "max_bytes": 1
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: `not_an_upload_project` (the project deploys from Git) or `too_many_uploads` (finish or cancel the others).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Deploy a dropped archive

```http
POST /v1/teams/{team}/projects/{project}/uploads/{upload}/complete
```

Say the browser has sent the zip. Orbits checks that it arrived whole and is a zip, then queues a production deployment that builds it (`trigger: manual`, the message is `Uploaded <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.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `upload`: The `id` from `POST .../uploads`.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads/upl_01jc8x6e4mq2v7r9y3t5b0zp8w/complete" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `202`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ]
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: `upload_incomplete` (not arrived yet) or `upload_expired` (start again).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Cancel a drop

```http
DELETE /v1/teams/{team}/projects/{project}/uploads/{upload}
```

Abandons an upload that was started and not completed; the file, if it arrived, is removed. Cancelling one that is gone or already completed is a no-op (the deployment it made is unaffected). Not needed for an upload that simply expires.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `upload`: The `id` from `POST .../uploads`.

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/uploads/upl_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Cancelled.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Set what production serves

```http
POST /v1/teams/{team}/projects/{project}/production
```

Points production at a deployment that served production before, and sets whether pushes may replace it. It is the Undo of a rollback (send back the rollback answer's `undo`), and with the current deployment and `auto_deploy_paused: false` it lifts a rollback's pause. No rebuild.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `deployment_id` (string, required)
- `auto_deploy_paused` (boolean, required)

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/production" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "auto_deploy_paused": false
  }'
```

Response `200`:

```json
{
  "deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "project": {
      "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    },
    "environment": "production",
    "state": "queued",
    "trigger": "git",
    "branch": "main",
    "sha": null,
    "message": "Update checkout copy",
    "author": {
      "name": "Shady Asaolu"
    },
    "created_by": {
      "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "my-app"
    },
    "url": "https://storefront-a1f9c2e.theorbits.app",
    "current": false,
    "went_live": false,
    "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "pull_request": null,
    "use_cache": false,
    "created_at": "2026-11-10T09:30:00Z",
    "started_at": "2026-11-10T09:30:00Z",
    "finished_at": "2026-11-10T09:30:00Z",
    "duration_seconds": null,
    "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
    "warnings": [
      {
        "kind": "missing_env",
        "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
        "keys": [
          "keys"
        ],
        "errors": [
          "errors"
        ],
        "blank": false
      }
    ]
  },
  "auto_deploy_paused": false
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## A deployment and its build steps

```http
GET /v1/teams/{team}/projects/{project}/deployments/{deployment}
```

The deployment page and the inspector: the header, the details grid (status, environment, duration, created, branch, commit, region, framework), production's domains when it is the current deployment, the six build steps with their state and seconds, and why a failed build stopped. The log lines themselves come from `GET .../logs`.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ],
  "framework": "Next.js 16",
  "region": "abj-1",
  "domains": [
    {
      "name": "storefront.theorbits.app",
      "state": "valid",
      "custom": false
    }
  ],
  "steps": [
    {
      "key": "queued",
      "state": "pending",
      "started_at": "2026-11-10T09:30:00Z",
      "finished_at": "2026-11-10T09:30:00Z",
      "seconds": null
    }
  ],
  "failure": {
    "title": "Type error in lib/cart.ts, line 42",
    "message": "Property 'total' does not exist on type 'Cart'.",
    "step": "queued",
    "line": null
  },
  "log_lines": 1,
  "open_graph": {
    "title": "Fifteen Seconds",
    "description": null,
    "image": "https://fifteen-seconds-85234cf.theorbits.app/og.png",
    "image_was_relative": false,
    "url": "https://my-app.theorbits.app",
    "site_name": null,
    "twitter_card": "summary_large_image",
    "twitter_title": null,
    "twitter_description": null,
    "twitter_image": "https://my-app.theorbits.app",
    "favicon": "https://my-app.theorbits.app",
    "fetched_at": "2026-11-10T09:30:00Z"
  }
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Build log lines

```http
GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs
```

The build log, oldest line first. Each line names its step, so the deployment page can group lines under Queued, Cloning repository, Installing packages, Building, Uploading and Going live. A build keeps at most 5000 lines.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Query parameters:

- `after` (integer): Return lines after this `n`. At least 0. Defaults to `0`.
- `limit` (integer): From 1 to 2000. Defaults to `500`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "n": 1,
      "at": "2026-11-10T09:30:00Z",
      "step": "queued",
      "tone": "plain",
      "text": "text"
    }
  ],
  "next_after": 1,
  "done": false
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Follow a build live (server-sent events)

```http
GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/logs/stream
```

The live build log, pushed as server-sent events (`text/event-stream`), for New project · Deploying, a building deployment and Follow output. Lines arrive under a second after the build prints them. Events:

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

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

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

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Query parameters:

- `after` (integer): The same as Last-Event-ID, for a first connection that already has lines. At least 0. Defaults to `0`.

Example:

```sh
curl -N "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/logs/stream" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200` (text/event-stream): The event stream.

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## A deployment's screenshot

```http
GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot
```

The image for the deployment inspector, the deployment page, New project's Preview box and the project card: the first screen (1280x800) of the deployment's home page, as a JPEG, taken by the builder a few seconds after the deployment became ready. It never changes once taken, so it is sent with `Cache-Control: private, max-age=604800, immutable`.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/screenshot" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -o screenshot.jpg
```

Response `200` (image/jpeg): The JPEG.

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Build the same commit again

```http
POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/redeploy
```

The Redeploy modal: builds this deployment's commit again in the same environment, as a new deployment. A production redeploy takes over production when it is ready; until then production keeps serving the current build. A deployment that failed before its commit was known rebuilds its branch's newest commit. A dropped upload is rebuilt from its stored archive; only the project's last 5 are kept, and an older one is 409 `source_expired` (drop the site again).

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Body:

- `use_cache` (boolean): Defaults to `true`.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/redeploy" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "use_cache": true
  }'
```

Response `202`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ]
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Promote to production

```http
POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/promote
```

The Promote modal: rebuilds a ready deployment's commit with production's environment variables, as a new production deployment that goes live when it is ready. The current version stays live until then. Promoting also lifts a rollback's pause on auto-deploy.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/promote" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `202`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ]
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Roll production back

```http
POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/rollback
```

Points production at an earlier production build straight away, with no rebuild, and pauses auto-deploy so the next push does not replace it (pushes still build; they just do not go live). The answer's `undo` restores what production served before, through `POST .../projects/{project}/production`.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/rollback" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "project": {
      "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app"
    },
    "environment": "production",
    "state": "queued",
    "trigger": "git",
    "branch": "main",
    "sha": null,
    "message": "Update checkout copy",
    "author": {
      "name": "Shady Asaolu"
    },
    "created_by": {
      "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "my-app"
    },
    "url": "https://storefront-a1f9c2e.theorbits.app",
    "current": false,
    "went_live": false,
    "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "pull_request": null,
    "use_cache": false,
    "created_at": "2026-11-10T09:30:00Z",
    "started_at": "2026-11-10T09:30:00Z",
    "finished_at": "2026-11-10T09:30:00Z",
    "duration_seconds": null,
    "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
    "warnings": [
      {
        "kind": "missing_env",
        "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
        "keys": [
          "keys"
        ],
        "errors": [
          "errors"
        ],
        "blank": false
      }
    ]
  },
  "auto_deploy_paused": false,
  "undo": {
    "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "auto_deploy_paused": false
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Cancel a build

```http
POST /v1/teams/{team}/projects/{project}/deployments/{deployment}/cancel
```

"Cancel deployment": a queued deployment is canceled at once; a building one is stopped by its builder within a few seconds (the answer still says `building`; poll until it says `canceled`). Nothing it built goes live.

**Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `deployment`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/deployments/dpl_01jc8x6e4mq2v7r9y3t5b0zp8w/cancel" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `202`:

```json
{
  "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "project": {
    "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "slug": "my-app",
    "name": "my-app"
  },
  "environment": "production",
  "state": "queued",
  "trigger": "git",
  "branch": "main",
  "sha": null,
  "message": "Update checkout copy",
  "author": {
    "name": "Shady Asaolu"
  },
  "created_by": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "name": "my-app"
  },
  "url": "https://storefront-a1f9c2e.theorbits.app",
  "current": false,
  "went_live": false,
  "redeploy_of": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "promoted_from": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "pull_request": null,
  "use_cache": false,
  "created_at": "2026-11-10T09:30:00Z",
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "duration_seconds": null,
  "screenshot_url": "/v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot",
  "warnings": [
    {
      "kind": "missing_env",
      "message": "VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.",
      "keys": [
        "keys"
      ],
      "errors": [
        "errors"
      ],
      "blank": false
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
