# API reference

NebulaCtrl's dashboard, CLI and MCP server all use the same REST API under `/api/v1`. Everything you can click, you can call. The pages below list every operation, grouped by area. They are generated from `openapi/openapi.json`; a running control plane also serves the spec at `/api/v1/openapi.json`.

## Authentication

There are two ways to authenticate:

| Method | Use it for |
|---|---|
| `Authorization: Bearer nct_…` | Scripts, CI and the CLI. Create a token under **Settings → API tokens**. Tokens are accepted only in this header, never in a query string. |
| The `nebulactrl_session` cookie | The dashboard. Cross-origin writes are rejected, so a browser page on another site cannot act as you. |

A token's **scopes** limit what it can do, and its project list can limit where. Scopes are intersected with the creator's role when the token is created and again on every use. See [API tokens](https://nebulactrl.com/docs/operations/teams.md#api-tokens).

| Scope | Allows |
|---|---|
| `projects:read` | Read projects, environments, services, deployments and logs |
| `projects:write` | Create and change projects, environments, services, variables and domains |
| `deployments:write` | Deploy, restart and stop services |
| `deployments:rollback` | Roll back a deployment |
| `servers:read` | Read servers and their metrics |
| `servers:write` | Enroll, change and revoke servers |
| `proxy:write` | Publish routes, expose TCP/UDP ports, certificates and tailnet egress |
| `admin` | Everything the creating member's role allows |

An operation marked **Public** needs no credentials, for example the first-run setup and sign-in calls.

## Errors

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` with an extra stable `code` field. Match on `code`, not on the message.

```json
{
  "status": 409,
  "code": "deployment_in_progress",
  "title": "Conflict",
  "detail": "another deployment of this service is active"
}
```

| Status | Meaning |
|---|---|
| `401` | No valid credentials: no session, or a missing, revoked or expired token |
| `403` | Credentials are valid but lack the scope or role, or the project is not allowed |
| `404` | Not found, **or not visible to you**. NebulaCtrl does not reveal whether a resource in another project exists |
| `409` | A conflict, such as `deployment_in_progress` or a name already taken |
| `412` | Stale `If-Match`: the resource changed since you read it (`generation_conflict`) |
| `422` | Valid JSON that fails validation. `errors` lists the fields |

## Conventions

- **Lists** are paginated with `?cursor=` and `?limit=` (default 50, maximum 200). The response carries `nextCursor` while more items exist.
- **Idempotency.** Mutating calls that create things accept an `Idempotency-Key` header (up to 255 characters). A retry with the same key replays the original response for 24 hours, so a flaky network cannot create two deployments.
- **Optimistic concurrency.** Updating a service takes `If-Match` with the generation you read. A mismatch returns `412` with `generation_conflict`.
- **Changes are staged.** Writing configuration, variables or domains stages the change and returns immediately. Nothing restarts until you call a deploy endpoint.
- **Deploy and rollback return `202`** with the deployment. They run asynchronously and never report success before the agent has finished; poll the deployment, or use `nebulactrl services deploy --wait`.
- **Secrets are write-only.** A secret variable is returned as `{key, isSecret: true, set: true}`, never its value.
- **Live updates** are Server-Sent Events: `GET /events` for resource changes, and the log endpoints with `follow=true`.

## Endpoints by area

Pick an area below, or use the search.

- [Analytics](https://nebulactrl.com/docs/reference/api/analytics.md): 3 operations.
- [Approvals](https://nebulactrl.com/docs/reference/api/approvals.md): 3 operations. Production approvals for AI clients
- [Audit](https://nebulactrl.com/docs/reference/api/audit.md): 1 operation. Audit log
- [Auth](https://nebulactrl.com/docs/reference/api/auth.md): 21 operations. Sessions
- [Backups](https://nebulactrl.com/docs/reference/api/backups.md): 21 operations.
- [Builds](https://nebulactrl.com/docs/reference/api/builds.md): 2 operations.
- [Canvas](https://nebulactrl.com/docs/reference/api/canvas.md): 2 operations. Canvas layouts
- [Certificates](https://nebulactrl.com/docs/reference/api/certificates.md): 3 operations.
- [Compose](https://nebulactrl.com/docs/reference/api/compose.md): 2 operations.
- [Databases](https://nebulactrl.com/docs/reference/api/databases.md): 17 operations.
- [Deployments](https://nebulactrl.com/docs/reference/api/deployments.md): 13 operations. Deployments and releases
- [Dns01](https://nebulactrl.com/docs/reference/api/dns01.md): 12 operations.
- [Domains](https://nebulactrl.com/docs/reference/api/domains.md): 10 operations. Service domains
- [Environments](https://nebulactrl.com/docs/reference/api/environments.md): 5 operations. Environments
- [Events](https://nebulactrl.com/docs/reference/api/events.md): 1 operation. Live invalidation feed
- [Fleet](https://nebulactrl.com/docs/reference/api/fleet.md): 6 operations.
- [Git](https://nebulactrl.com/docs/reference/api/git.md): 18 operations.
- [Imports](https://nebulactrl.com/docs/reference/api/imports.md): 2 operations.
- [Instance](https://nebulactrl.com/docs/reference/api/instance.md): 8 operations.
- [Integrations](https://nebulactrl.com/docs/reference/api/integrations.md): 12 operations.
- [Links](https://nebulactrl.com/docs/reference/api/links.md): 4 operations. Service links
- [Logs](https://nebulactrl.com/docs/reference/api/logs.md): 16 operations. Logs
- [Me](https://nebulactrl.com/docs/reference/api/me.md): 14 operations. Current principal
- [Mesh](https://nebulactrl.com/docs/reference/api/mesh.md): 9 operations.
- [Metrics](https://nebulactrl.com/docs/reference/api/metrics.md): 2 operations. Metrics
- [Networks](https://nebulactrl.com/docs/reference/api/networks.md): 6 operations.
- [Notifications](https://nebulactrl.com/docs/reference/api/notifications.md): 11 operations.
- [Platform](https://nebulactrl.com/docs/reference/api/platform.md): 13 operations.
- [Previews](https://nebulactrl.com/docs/reference/api/previews.md): 4 operations.
- [Projects](https://nebulactrl.com/docs/reference/api/projects.md): 5 operations. Projects
- [Proxy](https://nebulactrl.com/docs/reference/api/proxy.md): 6 operations.
- [Registries](https://nebulactrl.com/docs/reference/api/registries.md): 7 operations.
- [Routes](https://nebulactrl.com/docs/reference/api/routes.md): 5 operations.
- [Secret managers](https://nebulactrl.com/docs/reference/api/secret-managers.md): 5 operations.
- [Servers](https://nebulactrl.com/docs/reference/api/servers.md): 37 operations. Servers and agents
- [Services](https://nebulactrl.com/docs/reference/api/services.md): 23 operations. Services
- [Setup](https://nebulactrl.com/docs/reference/api/setup.md): 2 operations. First-run bootstrap
- [Shared variables](https://nebulactrl.com/docs/reference/api/shared-variables.md): 18 operations.
- [Stacks](https://nebulactrl.com/docs/reference/api/stacks.md): 1 operation.
- [System](https://nebulactrl.com/docs/reference/api/system.md): 1 operation. Control-plane info
- [Tasks](https://nebulactrl.com/docs/reference/api/tasks.md): 9 operations.
- [Teams](https://nebulactrl.com/docs/reference/api/teams.md): 19 operations. Teams, members, invites and instance settings
- [Templates](https://nebulactrl.com/docs/reference/api/templates.md): 8 operations.
- [Terminal](https://nebulactrl.com/docs/reference/api/terminal.md): 6 operations.
- [Tokens](https://nebulactrl.com/docs/reference/api/tokens.md): 3 operations. API tokens
- [Variables](https://nebulactrl.com/docs/reference/api/variables.md): 11 operations. Service variables
- [Volume backups](https://nebulactrl.com/docs/reference/api/volume-backups.md): 14 operations.
- [Volumes](https://nebulactrl.com/docs/reference/api/volumes.md): 3 operations. Service volumes

The complete machine-readable API is the OpenAPI 3.1 document at https://nebulactrl.com/api/v1/openapi.json.