API Reference

Everything you can do in the dashboard you can do with the API. Create projects, trigger deploys, run workflows, manage nodes, rotate secrets — all with a single bearer token. Use it to build CI bots, coding-agent integrations, or whatever else fits your workflow.

All endpoints accept and return JSON unless noted. The base URL for the hosted service is https://api.test.buildingswell.com — endpoint paths below are appended directly to it (there is no /api prefix).

Authentication

BTS supports two authentication methods:

Session cookies

The web dashboard signs in via GitHub OAuth or username/password and receives a JWT stored in an HTTP-only cookie. This is handled automatically when using the dashboard; API clients should use API keys instead.

API keys

For programmatic access, create an API key from Settings > API Keys in the dashboard (or via POST /auth/api-keys). Keys are prefixed with nxs_ and sent via the Authorization header:

curl https://api.test.buildingswell.com/projects \
  -H "Authorization: Bearer nxs_your_api_key_here"

API keys are hashed with bcrypt before storage. The plaintext key is shown only once at creation time — if you lose it, generate a new one.

Scopes

A key can be narrowed at creation time along three independent axes:

• scopes — a list of catalog permissions (below). The key may only perform operations covered by those permissions, and it can never exceed what its owner is allowed to do in a workspace. scopes: null (the default, and the behaviour of every key created before scopes existed) means the key inherits the full access of its owner.
• teamId — a workspace pin. The key only works against that one workspace (team or personal tenant).
• projectIds — a project pin. A key with a non-null projectIds is project-scoped: it may only act on those specific projects, and it is denied every workspace-level resource outright — nodes, quotas, teams and members, the activity feed, and creating projects. Endpoints marked with * in the tables below fall into that workspace-level category.

These are the permissions a key's scopes can grant:

⚠ marks a sensitive capability — it exposes secret material or grants a path to it (for example, a shell in the app container can read every injected secret).

Discovering your access

Three endpoints let a client (human or agent) work out what it can do without trial and error:

• GET /auth/me — returns the authenticated user and an auth object describing the credential in use. For API keys, auth.apiKey carries the key's scopes (an array, or null for full inherit), its teamId workspace pin, and its projectIds project pin — so a key can introspect its own grants.
• GET /auth/permissions — the full permission catalog (the table above), machine-readable.
• GET /openapi.json — this entire reference as an OpenAPI 3.1 document. Every operation carries its required permission in the x-required-permission extension, and the catalog is embedded as x-permission-catalog. No authentication required.

Per-project resolution is also available: GET /projects/:id returns access.permissions — exactly what the calling credential may do on that project after every narrowing (member override, key scopes, pins) is applied.

Endpoints

The Required scope column shows the catalog permission the endpoint enforces. auth only means any authenticated caller with access to the resource may call it; public means no authentication. A + joins permissions that are all required. * marks workspace-level endpoints, which are denied to project-scoped API keys regardless of scopes.

Errors

Failures return a JSON body { error, code }. error is a sentence to show a person and may be reworded; code is a stable snake_case identifier to branch on (project_not_found, permission_denied, plan_required, …). Every 4xx the API itself raises carries one, and a code is never renamed; the HTTP layer's own answers (an unknown route, an oversized or unsupported body) keep its FST_ codes. A project or environment outside your current workspace membership or principal project scope is the same 404 as a missing one (project_not_found, environment_not_found). A 403 caused by a missing capability is permission_denied and additionally includes requiredPermission. A project pin or member allow-list miss surfaced by a permission check is project_not_accessible (resource lookups hide it with 404 instead); a project-scoped principal calling a workspace route gets project_scope_restricted. Neither restriction can be fixed by granting a permission. Invalid input is invalid_request with an issues list of { path, message }. A rate limit is a 429 rate_limited; other 429s (a quota, a resume already in progress) carry their own code, often with a Retry-After header.

Example: create and use a scoped key

# Create a key that can only read deployments and stream one project
POST /auth/api-keys
{
  "name": "ci-status-bot",
  "scopes": ["projects:read", "deployments:read"],
  "projectIds": ["<project-uuid>"]
}

# → { "key": "nxs_…", "scopes": [...], "projectIds": [...] }  (key shown once)

# Verify what the key can do
curl https://api.test.buildingswell.com/auth/me -H "Authorization: Bearer nxs_…"
# → { "auth": { "method": "apiKey", "apiKey": { "scopes": [...], "projectIds": [...] } }, … }