# Projects

Create, read, change, pause and delete projects, and list the starter templates.

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

A project is one app: its source (a Git repository, or uploads), how it builds, and its addresses. Its `slug` is unique across Orbits, because it is the free address `<slug>.theorbits.app`; renaming a project changes it. `{project}` in a path is the slug or the `prj_` id. See [Projects](https://docs.orbits.africa/deploy/projects) for the guide.

Endpoints:

- `GET /v1/templates`: Starter templates for a new project
- `GET /v1/teams/{team}/projects`: List projects
- `POST /v1/teams/{team}/projects`: Create a project from a repository or a template
- `GET /v1/teams/{team}/projects/{project}`: Get a project
- `PATCH /v1/teams/{team}/projects/{project}`: Change project settings
- `DELETE /v1/teams/{team}/projects/{project}`: Delete a project
- `GET /v1/teams/{team}/projects/{project}/deletion-impact`: What deleting a project removes
- `POST /v1/teams/{team}/projects/{project}/pause`: Pause or resume a project

## The project object



- `id` (string, required)
- `slug` (string, required)
- `name` (string, required)
- `free_address` (string, required): Host name, `<slug>.theorbits.app`.
- `workload` (Workload, required)
  - `type` (string, required): Always `container`.
  - `output_directory` (string)
  - `spa_fallback` (boolean): Defaults to `false`.
  - `framework` (string)
  - `memory_mb` (integer): At least 128.
  - `timeout_seconds` (integer): At least 1.
  - `command` (array of string)
  - `replicas` (integer): At least 1. Defaults to `1`.
  - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker.
  - `port` (integer): From 1 to 65535.
  - `health_check_path` (string): Defaults to `/`.
  - `start_command` (array of string)
  - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`.
  - `dockerfile_path` (string or null)
- `source` (null or Source)
  - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`.
  - `repository` (string, required)
  - `production_branch` (string, required): Defaults to `main`.
  - `root_directory` (string): Defaults to `./`.
- `source_kind` (string): `upload`: deployed by dropping files (`POST .../uploads`); `source` is null and there is no repository. One of `git`, `upload`. Defaults to `git`.
- `build` (BuildConfig)
  - `framework` (string or null)
  - `install_command` (string or null): null means detected default.
  - `build_command` (string or null)
  - `output_directory` (string or null)
  - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`.
  - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday").
    - `id` (string)
    - `name` (string)
  - `changed_at` (string or null)
- `framework_version` (string or null): Shown next to the framework on the overview header, e.g. `15`.
- `node_version` (string)
- `region` (string, required)
- `status` (string, required): What the project cards and the project switcher show. `pending` means nothing has been deployed yet.
`building`, `ready` and `failed` follow the latest deployment (a canceled latest one falls back to production: `ready`, or `pending` if nothing served yet). One of `pending`, `building`, `ready`, `failed`, `paused`.
- `paused` (boolean)
- `git` (GitSettings, required)
  - `deploy_on_push` (boolean, required): Pushes to the production branch go to production; other branches get a preview.
  - `preview_pull_requests` (boolean, required): Each pull request gets its own address.
  - `comment_on_pull_requests` (boolean, required): Post the preview link on the pull request and update it on every push.
- `preview_protection` (string): Who may open previews (production stays public). `password`: the edge asks for the project's preview password and remembers it for 12 hours. One of `none`, `team_members`, `password`. Defaults to `team_members`.
- `production_url` (string or null)
- `latest_deployment_id` (string or null)
- `latest_deployment` (null or LatestDeployment)
  - `id` (string, required)
  - `state` (string, required): `queued` waits for a builder; the screens show it as building. One of `queued`, `building`, `ready`, `failed`, `canceled`.
  - `branch` (string or null)
  - `commit_sha` (string or null)
  - `commit_message` (string or null)
  - `author` (object or null)
    - `name` (string)
    - `avatar_url` (string or null)
  - `failure_reason` (string or null)
  - `created_at` (string, required)
- `thumbnail_url` (string or null): API path of the screenshot of what production serves, for the project card (the `screenshot_url` of that deployment). Null until production has one. Fetch it with the session, like any API call.
- `thumbnail_color` (string or null): The screenshot's most common strong colour, which the project card glows in. Null without a screenshot, or when the page is all black, white and grey.
- `created_at` (string, required)
- `updated_at` (string)
## Starter templates for a new project

```http
GET /v1/templates
```

The "Start from a template" catalog on the New project screens, read from [the-orbits/templates](https://github.com/the-orbits/templates) (its `catalog.json`, cached for five minutes). A template added there appears here without a backend change.

`workload` and `node_version`, when present, are what a project created from the template gets; `optional_env` lists variables the template reads when they are set. If the templates repository cannot be reached and nothing is cached, the list built into the service is served instead.

**Permissions:** Any signed-in user.

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

Example:

```sh
curl "https://api.theorbits.app/v1/templates" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "key": "store",
      "name": "Store",
      "description": "Product pages, cart, checkout",
      "category": "commerce",
      "framework": "nextjs",
      "framework_label": "Next.js",
      "required_env": [
        {
          "key": "PAYSTACK_SECRET_KEY",
          "hint": "From Paystack, Settings → API Keys."
        }
      ],
      "optional_env": [
        {
          "key": "PAYSTACK_SECRET_KEY",
          "hint": "From Paystack, Settings → API Keys."
        }
      ],
      "workload": {
        "type": "app",
        "port": 3000,
        "health_check_path": "/health"
      },
      "node_version": "24.x"
    }
  ]
}
```

Errors:

## List projects

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

The projects of a team, for the project cards on the team overview and for the project switcher.

Fields that come from deployments (`status`, `latest_deployment`, `thumbnail_url`) are `pending` or null until the deployment pipeline exists. Paused projects report `status: paused`.

Sorting: `last_deploy` (default) puts the most recently deployed first, then projects with no deployment by `created_at`.

An API token limited to one project may call this too: the list then holds only that project (still subject to `q` and `repository`), with `next_cursor: null`.

**Permissions:** Any team member, including viewers. A non-member gets 404, the same as an unknown team.

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

Path parameters:

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

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string)
- `q` (string)
- `sort` (string): One of `last_deploy`, `name`, `created`. Defaults to `last_deploy`.
- `repository` (string): Only projects imported from this repository, e.g. `shadyventures/storefront`.

Example:

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

Response `200`:

```json
{
  "next_cursor": null,
  "items": [
    {
      "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app",
      "free_address": "storefront.theorbits.app",
      "workload": {
        "type": "static",
        "output_directory": "dist",
        "spa_fallback": false
      },
      "source": {
        "provider": "github",
        "repository": "shadyventures/storefront",
        "production_branch": "main",
        "root_directory": "./"
      },
      "source_kind": "git",
      "build": {
        "framework": null,
        "install_command": null,
        "build_command": null,
        "output_directory": null,
        "ignore_command": null,
        "changed_by": {
          "id": "id",
          "name": "my-app"
        },
        "changed_at": "2026-11-10T09:30:00Z"
      },
      "framework_version": "15",
      "node_version": "22.x",
      "region": "abj-1",
      "status": "pending",
      "paused": false,
      "git": {
        "deploy_on_push": false,
        "preview_pull_requests": false,
        "comment_on_pull_requests": false
      },
      "preview_protection": "team_members",
      "production_url": "https://my-app.theorbits.app",
      "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "latest_deployment": {
        "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "state": "queued",
        "branch": null,
        "commit_sha": null,
        "commit_message": "Update checkout copy",
        "author": {
          "name": "my-app",
          "avatar_url": "https://my-app.theorbits.app"
        },
        "failure_reason": "Missing module 'mdsvex'",
        "created_at": "2026-11-10T09:30:00Z"
      },
      "thumbnail_url": "https://my-app.theorbits.app",
      "thumbnail_color": "#7c3aed",
      "created_at": "2026-11-10T09:30:00Z",
      "updated_at": "2026-11-10T09:30:00Z"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Create a project from a repository or a template

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

Create a project: the Deploy button on the New project > Configure screens.

`name` becomes the free address, `<slug>.theorbits.app`, where `slug` is the name in lower case with hyphens (or the `slug` you send). It must be unique across all teams: 409 means ask for another name.

`workload` is optional. When omitted it is derived from `build.framework`: `nextjs`, `sveltekit`, `nuxt`, `remix`, `reactrouter`, `solidstart` and `tanstack-start` become a `function`, `node`, `elysia` and `dolphjs` an `app`, and everything else `static`.

For a GitHub `source`, Orbits asks the Git service whether the team's GitHub connection can see the repository. 422 with `source.repository` means it cannot (not found, or not installed on that repository); 422 with `source.provider` means GitHub is not connected to the team. If that check cannot be completed the answer is 503 and nothing is created; retry.

With a `template` instead, Orbits creates a private repository named after the project's slug in the team's connected GitHub account, commits the template's files into it, and creates the project from it with the template's `workload` and `node_version`; the first deployment is queued as for an import. Every variable in the template's `required_env` must be sent in `env` (422 on `env` otherwise), and the address must be free before the repository is created. In a personal GitHub account the caller must have approved Orbits first (`GET /v1/teams/{team}/integrations/github/approval`). 409 covers a taken address, a repository of that name already in the account, GitHub not connected, a personal account not yet approved, and an organisation whose installation has not yet accepted the Orbits app's Administration and Contents permissions; its `detail` says which. 503 means GitHub could not be reached.

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

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

Path parameters:

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

Body:

- `name` (string, required): Also the source of the slug and free address, e.g. `checkout-v2`. At most 100 characters.
- `slug` (string)
- `workload` (Workload)
  - `type` (string, required): Always `container`.
  - `output_directory` (string)
  - `spa_fallback` (boolean): Defaults to `false`.
  - `framework` (string)
  - `memory_mb` (integer): At least 128.
  - `timeout_seconds` (integer): At least 1.
  - `command` (array of string)
  - `replicas` (integer): At least 1. Defaults to `1`.
  - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker.
  - `port` (integer): From 1 to 65535.
  - `health_check_path` (string): Defaults to `/`.
  - `start_command` (array of string)
  - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`.
  - `dockerfile_path` (string or null)
- `source` (Source)
  - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`.
  - `repository` (string, required)
  - `production_branch` (string, required): Defaults to `main`.
  - `root_directory` (string): Defaults to `./`.
- `template` (string): Template `key` from `GET /v1/templates`. Mutually exclusive with `source`: Orbits creates the repository in the team's GitHub account.
- `source_kind` (string): Default `git`. `upload` creates a project with no repository, deployed by dropping files (`POST /teams/{team}/projects/{project}/uploads`); no deployment is queued until the first drop. Not with `source` or `template`. One of `git`, `upload`.
- `build` (BuildConfig)
  - `framework` (string or null)
  - `install_command` (string or null): null means detected default.
  - `build_command` (string or null)
  - `output_directory` (string or null)
  - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`.
  - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday").
    - `id` (string)
    - `name` (string)
  - `changed_at` (string or null)
- `region` (string): Defaults to `abj-1`.
- `env` (array of object): Environment variables from the Configure step (Used by Production and Preview). They are saved with the project in one step; field errors come back as `env[0].key`. At most 500 items.
  - `key` (string, required): At most 255 characters.
  - `value` (string, required): May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on `EnvVar.value`. At most 32768 characters.
  - `environments` (array of string): Used by Production and Preview unless the user picks otherwise.
  - `sensitive` (boolean): Write-only: nobody can read the value back, only replace it. Defaults to `true`.

Example:

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

Response `202`:

```json
{
  "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "slug": "my-app",
  "name": "my-app",
  "free_address": "storefront.theorbits.app",
  "workload": {
    "type": "static",
    "output_directory": "dist",
    "spa_fallback": false
  },
  "source": {
    "provider": "github",
    "repository": "shadyventures/storefront",
    "production_branch": "main",
    "root_directory": "./"
  },
  "source_kind": "git",
  "build": {
    "framework": null,
    "install_command": null,
    "build_command": null,
    "output_directory": null,
    "ignore_command": null,
    "changed_by": {
      "id": "id",
      "name": "my-app"
    },
    "changed_at": "2026-11-10T09:30:00Z"
  },
  "framework_version": "15",
  "node_version": "22.x",
  "region": "abj-1",
  "status": "pending",
  "paused": false,
  "git": {
    "deploy_on_push": false,
    "preview_pull_requests": false,
    "comment_on_pull_requests": false
  },
  "preview_protection": "team_members",
  "production_url": "https://my-app.theorbits.app",
  "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "latest_deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "state": "queued",
    "branch": null,
    "commit_sha": null,
    "commit_message": "Update checkout copy",
    "author": {
      "name": "my-app",
      "avatar_url": "https://my-app.theorbits.app"
    },
    "failure_reason": "Missing module 'mdsvex'",
    "created_at": "2026-11-10T09:30:00Z"
  },
  "thumbnail_url": "https://my-app.theorbits.app",
  "thumbnail_color": "#7c3aed",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

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

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

One project, for the project overview header and for the Settings form.

**Permissions:** Any team member. A non-member, or a project in another team, gets 404.

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

Path parameters:

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

Example:

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

Response `200`:

```json
{
  "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "slug": "my-app",
  "name": "my-app",
  "free_address": "storefront.theorbits.app",
  "workload": {
    "type": "static",
    "output_directory": "dist",
    "spa_fallback": false
  },
  "source": {
    "provider": "github",
    "repository": "shadyventures/storefront",
    "production_branch": "main",
    "root_directory": "./"
  },
  "source_kind": "git",
  "build": {
    "framework": null,
    "install_command": null,
    "build_command": null,
    "output_directory": null,
    "ignore_command": null,
    "changed_by": {
      "id": "id",
      "name": "my-app"
    },
    "changed_at": "2026-11-10T09:30:00Z"
  },
  "framework_version": "15",
  "node_version": "22.x",
  "region": "abj-1",
  "status": "pending",
  "paused": false,
  "git": {
    "deploy_on_push": false,
    "preview_pull_requests": false,
    "comment_on_pull_requests": false
  },
  "preview_protection": "team_members",
  "production_url": "https://my-app.theorbits.app",
  "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "latest_deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "state": "queued",
    "branch": null,
    "commit_sha": null,
    "commit_message": "Update checkout copy",
    "author": {
      "name": "my-app",
      "avatar_url": "https://my-app.theorbits.app"
    },
    "failure_reason": "Missing module 'mdsvex'",
    "created_at": "2026-11-10T09:30:00Z"
  },
  "thumbnail_url": "https://my-app.theorbits.app",
  "thumbnail_color": "#7c3aed",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Change project settings

```http
PATCH /v1/teams/{team}/projects/{project}
```

Change project settings. Settings save as the user makes them (the Settings screen shows "All changes saved"), so send only the fields that changed.

Changes apply from the next deployment; existing deployments keep the snapshot taken when they were built. Renaming (`name`) also changes `slug` and the free address. The workload type cannot change after creation (422).

`build` and `git` are merged field by field: omit a field to keep it, send `null` in `build` to go back to the detected default. `preview_password` is write-only and only valid with `preview_protection: password`.

**Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

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

Body:

- `name` (string): At most 100 characters.
- `workload` (Workload)
  - `type` (string, required): Always `container`.
  - `output_directory` (string)
  - `spa_fallback` (boolean): Defaults to `false`.
  - `framework` (string)
  - `memory_mb` (integer): At least 128.
  - `timeout_seconds` (integer): At least 1.
  - `command` (array of string)
  - `replicas` (integer): At least 1. Defaults to `1`.
  - `schedule` (string or null): Cron expression for scheduled jobs; null for a continuous worker.
  - `port` (integer): From 1 to 65535.
  - `health_check_path` (string): Defaults to `/`.
  - `start_command` (array of string)
  - `image` (string or null): Prebuilt image reference. Mutually exclusive with `dockerfile_path`.
  - `dockerfile_path` (string or null)
- `source` (Source)
  - `provider` (string, required): One of `github`, `gitlab`, `bitbucket`, `gitbucket`.
  - `repository` (string, required)
  - `production_branch` (string, required): Defaults to `main`.
  - `root_directory` (string): Defaults to `./`.
- `build` (BuildConfig)
  - `framework` (string or null)
  - `install_command` (string or null): null means detected default.
  - `build_command` (string or null)
  - `output_directory` (string or null)
  - `ignore_command` (string or null): The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends `canceled`, saying why), anything else builds it. Two minutes at most, then it builds. It sees `ORBITS_GIT_COMMIT_SHA`, `ORBITS_GIT_COMMIT_REF` and `ORBITS_ENV`, and their `VERCEL_*` names. Example: `git diff --quiet HEAD^ HEAD -- ./apps/storefront`.
  - `changed_by` (object or null): Who last changed a build setting ("Changed by Tunde Bakare yesterday").
    - `id` (string)
    - `name` (string)
  - `changed_at` (string or null)
- `git` (object)
  - `deploy_on_push` (boolean)
  - `preview_pull_requests` (boolean)
  - `comment_on_pull_requests` (boolean)
- `node_version` (string)
- `preview_protection` (string): One of `none`, `team_members`, `password`.
- `preview_password` (string): Only with `preview_protection` `password`.
- `region` (string)

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "workload": {
      "type": "static",
      "output_directory": "dist",
      "spa_fallback": false
    },
    "source": {
      "provider": "github",
      "repository": "shadyventures/storefront",
      "production_branch": "main",
      "root_directory": "./"
    },
    "build": {
      "framework": null,
      "install_command": null,
      "build_command": null,
      "output_directory": null,
      "ignore_command": null,
      "changed_by": {
        "id": "id",
        "name": "my-app"
      },
      "changed_at": "2026-11-10T09:30:00Z"
    },
    "git": {
      "deploy_on_push": false,
      "preview_pull_requests": false,
      "comment_on_pull_requests": false
    },
    "node_version": "22.x",
    "preview_protection": "none",
    "preview_password": "preview-password",
    "region": "region"
  }'
```

Response `200`:

```json
{
  "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "slug": "my-app",
  "name": "my-app",
  "free_address": "storefront.theorbits.app",
  "workload": {
    "type": "static",
    "output_directory": "dist",
    "spa_fallback": false
  },
  "source": {
    "provider": "github",
    "repository": "shadyventures/storefront",
    "production_branch": "main",
    "root_directory": "./"
  },
  "source_kind": "git",
  "build": {
    "framework": null,
    "install_command": null,
    "build_command": null,
    "output_directory": null,
    "ignore_command": null,
    "changed_by": {
      "id": "id",
      "name": "my-app"
    },
    "changed_at": "2026-11-10T09:30:00Z"
  },
  "framework_version": "15",
  "node_version": "22.x",
  "region": "abj-1",
  "status": "pending",
  "paused": false,
  "git": {
    "deploy_on_push": false,
    "preview_pull_requests": false,
    "comment_on_pull_requests": false
  },
  "preview_protection": "team_members",
  "production_url": "https://my-app.theorbits.app",
  "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "latest_deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "state": "queued",
    "branch": null,
    "commit_sha": null,
    "commit_message": "Update checkout copy",
    "author": {
      "name": "my-app",
      "avatar_url": "https://my-app.theorbits.app"
    },
    "failure_reason": "Missing module 'mdsvex'",
    "created_at": "2026-11-10T09:30:00Z"
  },
  "thumbnail_url": "https://my-app.theorbits.app",
  "thumbnail_color": "#7c3aed",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

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

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

Delete a project (Settings > Delete project). The record is removed and an Operation is returned; downstream cleanup will be tracked by the same Operation once those services exist.

**Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

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

Example:

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

Response `202`:

```json
{
  "id": "op_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "kind": "team.delete",
  "state": "pending",
  "resource": "resource",
  "created_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "error": {
    "type": "https://my-app.theorbits.app",
    "title": "title",
    "status": 1,
    "detail": "detail",
    "instance": "instance",
    "request_id": "request-id",
    "code": "code",
    "required_plan": "pro",
    "feature": "functions",
    "errors": [
      {
        "field": "field",
        "message": "message"
      }
    ]
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## What deleting a project removes

```http
GET /v1/teams/{team}/projects/{project}/deletion-impact
```

The numbers on the Delete modal: "126 deployments and their build logs, 11 environment variables, 5 flags and their history, 4 domains are detached".

**Permissions:** Owner or admin, like the delete itself. A non-member gets 404.

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

Path parameters:

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

Example:

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

Response `200`:

```json
{
  "deployments": 1,
  "environment_variables": 1,
  "flags": 1,
  "domains": 1
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Pause or resume a project

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

Pause or resume a project (the Paused toggle in Settings > Advanced). While paused, its production, preview and custom-domain addresses answer 503 with Orbits' paused page, its apps stop, and nothing deploys; domains, data and the builds production can come back to stay. Resuming serves production again within moments.

The response is the updated Project (`paused` and `status: paused`), not an Operation: the toggle needs an immediate answer, and the runtime effect is reported through `status`.

**Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.

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

Path parameters:

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

Body:

- `paused` (boolean, required)

Example:

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

Response `200`:

```json
{
  "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "slug": "my-app",
  "name": "my-app",
  "free_address": "storefront.theorbits.app",
  "workload": {
    "type": "static",
    "output_directory": "dist",
    "spa_fallback": false
  },
  "source": {
    "provider": "github",
    "repository": "shadyventures/storefront",
    "production_branch": "main",
    "root_directory": "./"
  },
  "source_kind": "git",
  "build": {
    "framework": null,
    "install_command": null,
    "build_command": null,
    "output_directory": null,
    "ignore_command": null,
    "changed_by": {
      "id": "id",
      "name": "my-app"
    },
    "changed_at": "2026-11-10T09:30:00Z"
  },
  "framework_version": "15",
  "node_version": "22.x",
  "region": "abj-1",
  "status": "pending",
  "paused": false,
  "git": {
    "deploy_on_push": false,
    "preview_pull_requests": false,
    "comment_on_pull_requests": false
  },
  "preview_protection": "team_members",
  "production_url": "https://my-app.theorbits.app",
  "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "latest_deployment": {
    "id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "state": "queued",
    "branch": null,
    "commit_sha": null,
    "commit_message": "Update checkout copy",
    "author": {
      "name": "my-app",
      "avatar_url": "https://my-app.theorbits.app"
    },
    "failure_reason": "Missing module 'mdsvex'",
    "created_at": "2026-11-10T09:30:00Z"
  },
  "thumbnail_url": "https://my-app.theorbits.app",
  "thumbnail_color": "#7c3aed",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

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