Markdown

API

Interactive OpenAPI documentation is served by the API itself:

  • Swagger UI: /api/docs
  • Raw spec: /api/openapi.json

Request bodies in the spec are generated from the same zod schemas used for validation, so they can't drift.

Conventions

  • Base: /api/v1. JSON in, JSON out. Authorization: Bearer <token>.
  • Tokens: user access JWT, personal access token (slp_…), project secret key (slk_…, project-scoped).
  • Organizations and projects are addressed by slug or id: /orgs/{org}/projects/{project}/….
  • Errors: { "statusCode": 400, "message": "Validation failed", "issues": [{ "path": "email", "message": "…" }] }. A refused rollback adds reasons: string[].
  • Pagination: cursor based (limit, cursor → nextCursor).
  • Idempotency: Idempotency-Key on deploy/promote.
  • Rate limits: 429 with standard headers.
  • Real time: GET /orgs/{org}/events (Server-Sent Events, bearer-authenticated; use fetch streaming rather than EventSource).

Main resources

AreaEndpoints
Auth`POST /auth/registerloginrefreshlogoutforgot-passwordreset-passwordverify-email, GET /auth/providers, POST /auth/firebase` (Google or GitHub sign-in with a Firebase ID token)
MeGET/PATCH /me, POST /me/password, GET/POST/DELETE /me/tokens
OrgsPOST /orgs, GET/PATCH/DELETE /orgs/{org}, workspaces, members, invitations, GET /orgs/{org}/audit-logs
ProjectsGET/POST /orgs/{org}/projects, GET/PATCH/DELETE …/{project}, …/integration, members, environments, channels
ReleasesGET/POST …/releases, GET/PATCH …/releases/{id}, …/releases/compare, POST …/archive
ArtifactsPOST …/releases/{id}/artifacts (declare → signed URL), POST …/artifacts/{aid}/complete
LayoutsGET …/projects/{project}/layouts (verified ui-layout artifacts, newest first, with the channels serving each), GET …/layouts/{artifactId} (that layout's JSON). Read-only, release:read; publishing goes through releases
DeploymentsPOST …/releases/{id}/deployments, …/promote, GET /orgs/{org}/deployments
RolloutsGET /orgs/{org}/rollouts, GET …/rollouts/{id}, POST …/rollouts/{id}/actions
RollbacksGET …/rollbacks/preview, POST …/rollbacks, GET …/rollbacks
AnalyticsGET /orgs/{org}/dashboard, `/analytics/overviewtimelineversionsplatformserrorsreleases`
API keysGET/POST …/api-keys, POST …/{id}/rotate, DELETE …/{id}
IntegrationsGET …/integrations/catalog, webhook CRUD, …/test, …/deliveries
AdaptersGET /adapters, GET /adapters/{id} (public)

Delivery plane (separate port): POST /v1/updates/check, POST /v1/updates/events, GET /v1/artifacts/download (local driver only).

POST /v1/updates/check takes an optional kind (for example ui-layout or script-bundle). A release can carry several artifacts for one platform; with kind the device gets that artifact, without it the first deliverable one (what older SDKs expect). A release with nothing of that kind answers updateAvailable: false with reason: "no_deliverable_artifact".

Upload flow

text
POST …/releases/{id}/artifacts   { platform, kind, filename, size, sha256 }
  → { artifact, upload: { url, method: "PUT", headers, expiresAt } }
PUT <upload.url>                 (file bytes — directly to storage)
POST …/artifacts/{artifactId}/complete
  → artifact is verified asynchronously; poll GET …/releases/{id} until READY or FAILED

Send the bytes with any Content-Type (the dashboard sends application/json for a layout); the upload receiver never parses the body. During verification a ui-layout is also run through the layout checks, and a failure names the exact place, for example Invalid layout: screens.home.body.children[0].type: unknown component "carousel". A failed artifact can be uploaded again into the same release.