<!-- Stacklift documentation: "API". Source: https://stacklift.joynul.com/docs/api · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: REST conventions, resources, the upload flow and the delivery plane.

# 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

| 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

```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.
