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 addsreasons: string[]. - Pagination: cursor based (
limit,cursor→nextCursor). - Idempotency:
Idempotency-Keyon deploy/promote. - Rate limits: 429 with standard headers.
- Real time:
GET /orgs/{org}/events(Server-Sent Events, bearer-authenticated; usefetchstreaming rather thanEventSource).
Main resources
| Area | Endpoints | ||||||
|---|---|---|---|---|---|---|---|
| Auth | `POST /auth/register | login | refresh | logout | forgot-password | reset-password | verify-email, GET /auth/providers, POST /auth/firebase` (Google or GitHub sign-in with a Firebase ID token) |
| Me | GET/PATCH /me, POST /me/password, GET/POST/DELETE /me/tokens | ||||||
| Orgs | POST /orgs, GET/PATCH/DELETE /orgs/{org}, workspaces, members, invitations, GET /orgs/{org}/audit-logs | ||||||
| Projects | GET/POST /orgs/{org}/projects, GET/PATCH/DELETE …/{project}, …/integration, members, environments, channels | ||||||
| Releases | GET/POST …/releases, GET/PATCH …/releases/{id}, …/releases/compare, POST …/archive | ||||||
| Artifacts | POST …/releases/{id}/artifacts (declare → signed URL), POST …/artifacts/{aid}/complete | ||||||
| Layouts | GET …/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 | ||||||
| Deployments | POST …/releases/{id}/deployments, …/promote, GET /orgs/{org}/deployments | ||||||
| Rollouts | GET /orgs/{org}/rollouts, GET …/rollouts/{id}, POST …/rollouts/{id}/actions | ||||||
| Rollbacks | GET …/rollbacks/preview, POST …/rollbacks, GET …/rollbacks | ||||||
| Analytics | GET /orgs/{org}/dashboard, `/analytics/overview | timeline | versions | platforms | errors | releases` | |
| API keys | GET/POST …/api-keys, POST …/{id}/rotate, DELETE …/{id} | ||||||
| Integrations | GET …/integrations/catalog, webhook CRUD, …/test, …/deliveries | ||||||
| Adapters | GET /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
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 FAILEDSend 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.