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{}ajourney, a na úrovni sessioncommitabranch.
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=. |