API reference

Every endpoint you need to manage projects, deploys, logs, databases and secrets — for CI, scripts, or AI agents.

Base URL & authentication

•Base URL: https://api.example.com. All app/project routes are tenant-scoped under /tenants/<tenantId>/…
•Auth: send a personal access token as a bearer header — Authorization: Bearer shpat_… A token acts as you, scoped to your workspace only (no platform-admin routes). The browser console uses a session cookie instead; both resolve to the same permissions.
•Content type: application/json for request bodies. Responses are JSON; log streams are Server-Sent Events (text/event-stream).
•Resolve your IDs first: GET /auth/me → memberships[0].tenantId; GET /tenants/<tenantId>/projects → project ids; GET /tenants/<tenantId>/projects/<projectId> → environments[].id.

•GET /tenants/<t>/projects — list projects (supports ?search=&status=&page=).
•POST /tenants/<t>/projects — create a project { name, type: static|react|node|python, repositoryConnectionId, rootDirectory?, productionBranch?, runsServer?, config? }.
•POST /tenants/<t>/projects/detect — inspect a connected repo { repositoryConnectionId, branch?, rootDirectory? } → suggested { type, runsServer, install/build/start, framework, evidence, confidence }.
•GET /tenants/<t>/projects/ — project detail (incl. environments, build + runtime config).
•PATCH /tenants/<t>/projects/ — update name/description/rootDirectory/status.
•PATCH /tenants/<t>/projects//build-config — install/build/output/rootDirectory/nodeVersion/packageManager.
•PATCH /tenants/<t>/projects//runtime-config — runtimeType (static|node|python)/startCommand/port/healthCheckPath/limits/instances.

•POST /tenants/<t>/projects//environments/<e>/deployments — trigger a deploy { branch?, note? }. Returns the deployment (incl. its DEP-#### ref).
•GET /tenants/<t>/projects//deployments — list deployments (?environmentId=&status=&page=).
•GET /tenants/<t>/deployments/<id> — deployment detail (status, error, release, events).
•GET /tenants/<t>/deployments/<id>/logs?after=<seq> — historical build logs.
•GET (SSE) /tenants/<t>/deployments/<id>/stream — live build logs + status.
•POST /tenants/<t>/deployments/<id>/cancel · POST /tenants/<t>/deployments/<id>/retry.
•POST /tenants/<t>/rollback { releaseId, reason? } — re-activate a previous release (no rebuild).

•GET /tenants/<t>/projects//releases?environmentId=<e> — release history (rollback targets).
•GET /tenants/<t>/projects//environments/<e>/runtime — live URLs, active release, runtime instance, routes, domains.
•GET /tenants/<t>/releases/<releaseId>/runtime-logs?after=<seq> and (SSE) /runtime-logs/stream — Node/Python container logs.
•GET /tenants/<t>/projects//environments/<e>/access-logs?after=<id> and (SSE) /access-logs/stream — Static/React access log (4xx/5xx + non-GET).

•Secrets: GET/POST /tenants/<t>/secrets · PATCH/DELETE /tenants/<t>/secrets/<id> (scope: project, environment, or whole workspace).
•Managed databases: GET/POST /tenants/<t>/databases · GET /tenants/<t>/databases/<id> · POST .../start|stop|attach · DELETE; backups under .../backups.
•Custom domains: GET/POST /tenants/<t>/projects//domains · POST .../<domainId>/verify · DELETE.
•API tokens: GET/POST /account/api-tokens · DELETE /account/api-tokens/<id> (session-only; manage your own tokens).

•Errors: non-2xx responses carry { statusCode, error, message }. A failed deploy also exposes a human-readable error field on GET /deployments/<id> and folds the failing output into the build log.
•Quotas: deploys are rate-limited per workspace per day (429/403 when exceeded).
•SSE: connect with EventSource; each message is a JSON frame { type: "log"|"status"|"done", … }. Reconnect from the last seq/cursor.
•Full deploy walkthrough + troubleshooting: see “Deploy with the API (CLI, CI & AI agents)”.