HTTP API

Každá část je dostupná přes obyčejné HTTP a k publikování nepotřebujete nic než `tar` a `curl`. Tohle je kontrakt, kterým mluví CLI, MCP server i rekordéry.

Ověření

Každý požadavek je ověřený. Strojoví klienti nesou token omezený na workspace, prohlížeče session cookie. Router určí workspace z cesty /w/<slug> nebo přímo z tokenu a pak požadavek prověří proti roli.

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

Zápisy na nástěnku se navíc připisují, což není totéž co ověření: vyhrává identita udělená tokenu agenta, pak deklarovaný X-Board-Actor, pak přihlášený uživatel. Prohlížeč přes X-Board-Actor nikoho nezastoupí.

Health check

Vlastní health check kontejneru. Bez ověření.

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

Publikování sady

Kanonický jednořádkový příkaz. Nahraje adresář jako sadu a je idempotentní — spuštěním znovu obsah nahradíte na místě.

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"

Klíč je váš — {key} je alias, který si zvolíte sami, ve tvaru [a-zA-Z0-9._-]{1,64} — sdílecí URL tak znáte dřív, než se nahraje první bajt.
Nemáte klíč? — POST /api/v1/sets?project=…&branch=… vám ho vygeneruje.
První nahrání → 201 — a nová verze. Opakované PUT téhož klíče → 200, stejná verze, obsah nahrazen.

Parametry publikování

Všechny volitelné, všechny v query stringu. Právě ony brání tomu, aby snímek ztratil kód, ze kterého vznikl.

Parametr	Výchozí	Co nese
`kind`	`screenshots`	O jaký druh sady jde.
`branch`	—	Větev, na které práce vznikla.
`commit`	—	Commit, který ji vytvořil.
`pr`	—	Číslo pull requestu.
`issue`	—	Odkaz do trackeru — issue v Plane dostane jeden aktualizovaný komentář na sadu.
`title`	—	Lidský název sady.
`repo`	—	Repozitář, ze kterého sada přišla.

MAX_SET_MB (výchozí 200) omezuje tělo požadavku i rozbalenou velikost.

Odpověď

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

Manifest

manifest.json uvnitř tar souboru řídí odznaky v galerii, routy, poznámky i seskupení po dnech. Sada bez manifestu se nahraje taky — přijdete o metadata, ne o upload.

{
  "version": 1,
  "shots": [
    { "file": "01-cart.png", "surface": "cart", "route": "/cart", "note": "sleva se počítá dvakrát", "ts": "…" }
  ]
}

Verze 2 přidává — u snímku src[], state, device{} a journey, a na úrovni session commit a branch.

JSON endpointy

Endpoint	Co dělá
`GET /api/v1/projects`	Všechny projekty.
`GET /api/v1/sets/{project}[/{branch}]`	Výpisy sad.
`GET /api/v1/sets/{project}/{branch}/{selector}`	Metadata jedné sady.
`PATCH /api/v1/sets/{project}/{branch}/{selector}`	Úprava `{"name","title"}` — name je slug malými písmeny, unikátní v rámci projektu a větve.
`POST /api/v1/sets`	Vygeneruje klíč sady.
`PUT` · `GET /api/v1/projects/{project}/index`	Nahrání nebo čtení indexu pro `@` doplňování.
`GET /api/v1/library`	Prohledávací plátno napříč sadami. Také `/facets` a `/screen?key=`.

Adresy pro lidi, které sada dostane. Nejsou pod /api/v1 — jsou to stránky, které někomu pošlete.

Adresa	Co vrací
`/{project}/{branch}/{version}`	Prohlížeč sady — galerie, nebo sandboxovaný iframe, pokud sada obsahuje `index.html`.
`/{project}/{branch}/latest`	302 na nejnovější verzi.
`/{project}/{branch}/{key}`	302 na kanonickou URL té sady.
`/{project}/{branch}/{version}.zip`	Streamovaný zip celé sady.
`/{project}/{branch}/{version}/files/{path}`	Surová data s ETagem a dlouhou cache.
`/{project}/{branch}/{version}/raw/{path}`	Tatáž data, CSP-sandboxovaná — tohle je src iframu pro HTML artefakty.
`/boards` · `/boards/{slug}`	Anotační nástěnky.
`/library`	Prohledávací plátno snímků napříč sadami.

Sada může nést upravitelné jméno — slug malými písmeny, unikátní v rámci projektu a větve — takže …/myapp/main/payout-flow funguje vedle …/myapp/main/2.

Na této stránce