HTTP API

Authentication

Every request is authenticated. vitrinka auth login mints a personal token and MCP hosts hold an OAuth token; both act as you, so name the workspace per request with X-Vitrinka-Workspace: <slug> — the CLI sends it from the repository's binding. Without the header, a personal token resolves only when you belong to exactly one team workspace, or when the project in the path exists in exactly one of yours — otherwise a structured 401 lists your workspaces; an OAuth token without it lands in its connection's default workspace, and one naming a workspace the connection does not reach gets 403 workspace_not_connected. Service and agent tokens are pinned to one workspace. Recorder tokens (vkr_) and report-widget keys (vkb_) are publishable and origin-allowlisted: a report key can only ingest into its one project, and a recorder token acts only on the sessions it started itself (recorder credentials). Browsers carry a session cookie. The tenant router resolves the workspace, then role-gates the request.

curl -sS -H "Authorization: Bearer $VITRINKA_TOKEN" \
  -H "X-Vitrinka-Workspace: acme" \
  "$VITRINKA_URL/api/v1/projects"

Recovering from errors

API failures preserve their HTTP status and return error, code, detail and fix. Specific failures also include currentRevision, didYouMean, or validation diagnostics; preserve these when forwarding an error. Unknown JSON fields are rejected with accepted field names. Bodies must contain exactly one JSON value within the endpoint's size limit.

Read code to classify the failure and fix for the next action. A 401 may require authentication; a 403 calls for the correct workspace, role or scope, or reports a limit reached or writes paused by an expired licence — retrying unchanged does not help. Before retrying a write after a timeout or gateway failure, read the resource to check whether the write already took effect. Respect Retry-After and Allow. OAuth endpoints retain their OAuth error contract.

MCP tool failures set isError: true and expose the same diagnostic object in both text content and structuredContent. Protocol failures retain their JSON-RPC code and put recovery details in error.data.

Health

The container's own health check. No authentication.

curl -sS "$VITRINKA_URL/healthz"
# {"ok":true,"mode":"multitenant"}

Publishing a set

The canonical one-liner. It syncs a directory as a set and is idempotent — re-run it to replace the content in place.

tar czf - -C ./screenshots . | curl -sS -X PUT --data-binary @- \
  -H "Authorization: Bearer $VITRINKA_TOKEN" \
  "$VITRINKA_URL/api/v1/sets/myapp/main/s-20260823-1431/content?kind=screenshots&commit=a34ec8e&pr=42"

• The key is yours — {key} is a client-generated alias matching [a-zA-Z0-9._-]{1,64}, so you know the blob addresses before the first byte uploads; the url in the response is the set's home (a document card /a/<id> or a journey board /boards/<slug>).
• No key handy? — POST /api/v1/sets?project=…&branch=… generates one for you.
• First upload → 201 — with a fresh version. Re-PUT of the same key → 200, same version, content replaced.
• Or one file at a time — a screenshot set also syncs file by file, the way vitrinka board push does: GET …/{key}/files is the have-list (path → sha256), PUT …/{key}/files/{path} with X-Content-SHA256 uploads one file of up to 25 MiB (If-None-Match answers 304 for bytes the set already holds), and POST …/{key}/commit prunes what the folder lost and writes the set's metadata. Landed shots join the set's board within seconds. Artifact sets keep the tarball door.

Publish parameters

All optional, all query-string. They are what stops a screenshot from being orphaned from the code that made it.

Publish response

{
  "url": "…",
  "project": "myapp",
  "branch": "main",
  "version": 7,
  "key": "s-20260823-1431",
  "kind": "screenshots",
  "files": 24,
  "bytes": 5312004,
  "created": true
}

created is true on the first upload of a key. An artifact push adds diagnostics, screenshot (the smoke render), docCard (the document's /a/<id>) and pages.

The manifest

A manifest.json inside the tarball drives gallery badges, routes, notes and day grouping. A set with no manifest still ingests — you lose the metadata, not the upload.

{
  "version": 1,
  "shots": [
    { "file": "01-cart.png", "surface": "cart", "route": "/cart", "note": "discount applies twice", "ts": "…" }
  ]
}

• Version 2 adds — per-shot src[], state, device{} and journey, plus session-level commit and branch.

JSON endpoints

Share URLs

These are the human-facing addresses a set gets. They are not under /api/v1. The one to send to somebody is the url in the publish response — the set's home, a document card or a journey board; the old set addresses only redirect there.

The other families

Sets are the oldest door; the product has grown many more under /api/v1, and the CLI, the MCP endpoint and the browser all speak them. Every family pages — nothing reads a whole project. Board writes are attributed as above; task-engine writes record the verified identity only — an X-Board-Actor label never becomes the ledger actor.

The task engine

Tasks are keyed by id across the workspace and scoped to a project on listing. A list takes the same filter document the browser's filter bar edits, ?f=<base64url json>, and pages with a keyset cursor that carries its own order — a cursor from one order is refused on another.

Binding a mirror, running a sync, authoring rules and recording deploys are admin actions, and merging or transferring a project is the workspace owner's; everything else is member-level. The full model is the Product tab.

Live events

GET /api/v1/events is one Server-Sent Events stream per workspace — the bus the browser app itself runs on — so a script can follow the workspace instead of polling list endpoints. ?project= narrows it to one project; ?kind= (repeatable, or comma-separated) picks from task, annotation, board, sidebar, favorites, workspace-settings, prefs, project, agenda and decision, and an unknown kind is a 400 that names it.

curl -sN -H "Authorization: Bearer $VITRINKA_TOKEN" \
  -H "X-Vitrinka-Workspace: acme" \
  "$VITRINKA_URL/api/v1/events?project=shop&kind=task,annotation"

Each frame is id:, event: (the kind) and data: — one ledger row with its kind, project, ref, actor, createdAt and a typed data payload — with a comment ping every 25 seconds. Resume with the Last-Event-ID header, or ?after=<id>; without a cursor the stream starts at the head. Rows are durable and kept 30 days, so a reconnect after sleep or a deploy replays everything it missed. It authenticates like any /api/v1 call, workspace included.

A decision frame follows Needs you (GET /api/v1/human/decisions): one decision moved in or out of it, whichever door moved it — the app, the CLI, MCP, an agent's hand-back, a rule. Its ref is the decision's id in that read's grammar, and data says what happened:

{ "id": 4182, "kind": "decision", "project": "shop", "ref": "gate:42:3f2a9c01de", "actor": "Ada",
  "createdAt": "2026-10-16T09:12:03Z",
  "data": { "op": "resolved", "kind": "gate", "taskId": 42, "gate": "Approve copy" } }

Only gate:<task>:<handle> and todo:<task> name one row: a client that holds it can settle it on resolved or withdrawn. ask:<board> is the board's folded row, gone only when count is 0; intake:<draft> names a draft (its family's row only when it heads one) and plan:<project>:<goal>:<day> the goal-day a move belongs to (a full one continues on :<part> cards), so both always re-read. So do raised, changed and any ref the client does not hold: Needs you alone knows whom a decision waits on and what a folded row still holds. A frame is visible to whoever may see what it is about: task decisions to the workspace, a personal board's asks to its owner. A todo falling due with the clock is not a write, so it is not a frame — Needs you finds it on the next read.

Recorder reports and policy

The embeddable report widget and the browser recorder talk to two small families the QA pages describe from the tester's side.

Identity, licence and version

The AI backend proxy

/api/v1/eve/{path} forwards requests from project, task and board conversations to the configured AI backend. Its interface is the AI backend protocol, docs/ai-backend-protocol.md in the server's source. Workspace backend settings override AI_BACKEND_URL and AI_BACKEND_TOKEN. Mutating calls to the managed backend require AI credits; reads and workspace-owned compute do not.

OAuth for MCP hosts

Hosts connect to /mcp (or /w/<workspace>/mcp) as public OAuth 2.1 clients: authorization code with mandatory PKCE, discovered from /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource (also with the /mcp and /w/<slug>/mcp suffixes); registration by client-ID metadata document or POST /oauth/register (the latter alone under AIR_GAP=1); the flow is GET and POST /oauth/authorize and POST /oauth/token, with rotating refresh tokens. A grant is scoped read or read write and reaches the workspaces ticked on consent — by default every team workspace of your organisations, later ones included; Personal only when ticked — editable later in Settings → Connected apps without a new sign-in. Its default workspace takes calls that name none (an MCP call naming a project that one other reached workspace alone knows lands there; one several know is refused with each spelling); every other reached workspace is one header or <workspace>/<project> away; a workspace outside the reach answers 403 workspace_not_connected with a manage_url. POST /oauth/revoke (RFC 7009) retires a connection; users disconnect connections and admins remove them from their workspace in their connection lists — MCP for any client.