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ý. vitrinka auth login vydá osobní token a MCP hostitelé drží OAuth token; oba jednají za vás, takže workspace jmenujte u každého požadavku hlavičkou X-Vitrinka-Workspace: <slug> — CLI ji posílá podle vazby repozitáře. Bez hlavičky se osobní token vyřeší jen tehdy, když patříte do právě jednoho týmového workspace, nebo když projekt v cestě existuje právě v jednom z vašich — jinak strukturovaná 401 vypíše vaše workspace; OAuth token bez ní přistane ve výchozím workspace svého připojení a s workspace, na který připojení nedosáhne, dostane 403 workspace_not_connected. Servisní a agentní tokeny jsou připnuté k jednomu workspace. Tokeny rekordéru (vkr_) a klíče widgetu hlášení (vkb_) jsou veřejně publikovatelné a omezené na povolené originy: klíč hlášení umí jen nahrávat do svého jednoho projektu a token rekordéru jedná jen se sessions, které sám založil (přístupy rekordéru). Prohlížeče nesou session cookie. Router určí workspace a pak požadavek prověří proti roli.

curl -sS -H "Authorization: Bearer $VITRINKA_TOKEN" \
  -H "X-Vitrinka-Workspace: acme" \
  "$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í.

Náprava chyb

Chybová odpověď API zachovává HTTP status a obsahuje error, code, detail a fix. Konkrétní chyby navíc nesou currentRevision, didYouMean nebo validační diagnostics; při předávání chyby tyto údaje zachovejte. Neznámá pole JSON jsou odmítnuta se seznamem povolených polí. Tělo musí obsahovat právě jednu hodnotu JSON v rámci velikostního limitu daného endpointu.

Pole code určuje druh chyby a fix další krok. Status 401 může vyžadovat přihlášení; 403 vyžaduje správný workspace, roli nebo oprávnění, případně hlásí dosažený limit nebo zápisy pozastavené prošlou licencí — beze změny opakování nepomůže. Před opakováním zápisu po timeoutu nebo chybě brány načtěte objekt a ověřte, zda se zápis již neprovedl. Respektujte hlavičky Retry-After a Allow. OAuth endpointy zachovávají vlastní chybový protokol.

Chyby nástrojů MCP nastavují isError: true a vracejí stejný objekt diagnostiky v textovém obsahu i v structuredContent. Chyby protokolu zachovávají kód JSON-RPC a přidávají pokyny k nápravě do error.data.

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} — adresy souborů tak znáte dřív, než se nahraje první bajt; url v odpovědi je domov sady (dokumentová karta /a/<id> nebo journey nástěnka /boards/<slug>).
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.
Nebo soubor po souboru — sada snímků se synchronizuje i po jednotlivých souborech, tak jako to dělá vitrinka board push: GET …/{key}/files je seznam toho, co server má (cesta → sha256), PUT …/{key}/files/{path} s X-Content-SHA256 nahraje jeden soubor do 25 MiB (If-None-Match odpoví 304 pro bajty, které sada už drží) a POST …/{key}/commit odebere, co ze složky zmizelo, a zapíše metadata sady. Nahrané snímky se během pár sekund objeví na nástěnce sady. Sady s artefaktem zůstávají u dveří pro tar.

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.
`source`	—	Křížový odkaz na zdrojovou sadu, `project/branchSlug/key`.

MAX_SET_MB (výchozí 200) omezuje tělo požadavku i rozbalenou velikost u dveří pro tar. Dveře pro jednotlivé soubory omezují každý soubor na 25 MiB; sada pojme libovolný počet souborů a její seznam (GET …/files?limit=N&after=<next>) se čte po stránkách.

Odpověď

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

created je true při prvním nahrání klíče. Push artefaktu přidá diagnostics, screenshot (kontrolní vykreslení), docCard (/a/<id> dokumentu) a pages.

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í.
`PUT` · `GET` · `DELETE /api/v1/projects/{project}/icon` · `POST …/icon/fetch`	Ikona projektu: `PUT` přijme bajty obrázku jako tělo (typ se pozná z obsahu; normalizuje se na PNG nejvýš 256 px, bezpečné SVG zůstává), `POST …/icon/fetch` `{url?}` ji načte z veřejného webu — ve výchozím stavu z produkční domény, na instalaci odpojené od internetu odmítnuto. `POST /api/v1/workspace/logo/from-project` `{project}` z ní udělá logo workspace (admin).
`GET /api/v1/library`	Prohledávací plátno napříč sadami. Také `/facets` a `/screen?key=`.
`GET /api/v1/artifacts`	Jediné dveře k artefaktům — dokumentové a stránkové karty a sady artefaktů napříč projekty, stránkované kurzorem (`?cursor=`, `?limit=`); zúžené přes `?project=`, `?tag=`, `?kind=`, `?branch=` (seznamy oddělené čárkou) a `?q=`; `?facets=1` přidá k první stránce druhy, větve a projekty. Čte ho Knihovna › Artefakty i Záznam › Artefakty projektu.
`GET /api/v1/library/boards?limit=`	Stránka prohlížeče nástěnek — všechny živé nástěnky od nejnovější aktivity, stránkované kurzorem (`?limit=` až 200 vybírá tento tvar, `?cursor=` v něm pokračuje); zúžené přes `?project=`, `?type=`, `?tags=`, `?fav=1` a `?q=`; `?type=` jmenuje jeden ze šesti druhů nástěnek (`docs`, `artifacts`, `brainstorm`, `qa`, `sessions`, `board`; jiné slovo zúží podle uloženého typu) a `?facets=1` přidá k první stránce druhy s počty; každý řádek nese svůj `kind`. Kurzor použitý s jinými filtry je odmítnut a odpověď jmenuje filtry, se kterými vznikl.
`GET /api/v1/library/favorites`	Vaše oblíbené jako jeden seznam — `?scope=` (`all`, `mine` nebo `workspace`), `?folder=`, `?kind=`, `?project=` — s počty všech tří rozsahů.
`GET /api/v1/memory`	Plochý seznam paměti knihovny — paměťový dokument každého projektu a paměťové stránky přihlášeného člověka, stránkované kurzorem (`?project=`, `?cursor=`). Každý řádek uvádí svůj `source` (`project` · `personal`); `?facets=1` přidá k první stránce projekty, které paměť mají.
`PUT /api/v1/projects/{project}/islands/{island}/snapshots/{commit}` · `GET …/current` · `PUT …/usage` · `GET …/note?path=`	Cloudová cache paměťových ostrovů: memo publikuje jeden snapshot mergnutého commitu na ostrov (`{island}` URL-escapovaný, `project%2Facme`) přes `vitrinka memory snapshot put`; `current` se posune jen porovnáním a záměnou podle `parent` snapshotu (`409 cas_mismatch` uvede ten cloudový), chybný snapshot je `422 snapshot_invalid` se svým `field`. Cache drží 20 snapshotů na ostrov. `GET /api/v1/projects/{project}/memory/index` je omezený index, který čte MCP `get {kind: "project_memory"}` — nejdřív připnuté řádky, pak druh × čerstvost plus synchronizované použití, `{commit, complete, omitted, next}`; jakmile snapshot nese `notes/legacy-project-memory.md`, `PUT …/memory` odpoví `409 legacy_put` a tělo si ponechá jako návrh (`GET …/memory/proposals`).

Adresy pro lidi, které sada dostane. Nejsou pod /api/v1. Někomu posíláte url z odpovědi na publikování — domov sady, tedy dokumentovou kartu nebo journey nástěnku; staré adresy sady tam jen přesměrují.

Adresa	Co vrací
`/{project}/{branch}/{version}`	301 na domov sady: její dokumentovou kartu `/a/<id>` (doc.json → doc karta, `index.html` → html karta, ostatní soubory → doc karta se seznamem souborů) nebo její journey nástěnku `/boards/<slug>` (screenshoty).
`/{project}/{branch}/latest` · `/{key}` · `/{name}`	302 na tentýž domov.
`/{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 html karty.
`/boards` · `/boards/{slug}`	Anotační nástěnky — `/boards` je ukazuje jako karty, malé karty, tabulku nebo přiblížitelnou stěnu, od nejnovější aktivity (`?layout=` a filtry stěny `?project=`, `?tag=`, `?type=`, `?fav=1` a `?q=`); `/boards/{slug}` nástěnky dokumentace otevře její čtečku na `/docs/{slug}` (`?canvas=1` ponechá plátno).
`/docs` · `/docs/{slug}` · `/docs/artifacts`	Dokumentace — nástěnky dokumentace všech projektů (`GET /api/v1/docs-boards`), jedna nástěnka čtená jako obsah a stránky (`GET /api/v1/boards/{slug}/docs`; `?page=` jmenuje otevřenou stránku) a všechny artefakty jako karty, malé karty nebo tabulka.
`/library`	Modul Knihovna — přesměruje na `/library/screens`, prohledávací plátno snímků napříč sadami; `/library/memory` seznam paměti, `/library/favorites` oblíbené jako jeden seznam (Vše · Moje · Pracovní prostor). `/library/boards` a `/boards/library` přesměrují na `/boards`, `/library/artifacts` na `/docs/artifacts`.

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 přesměruje stejně jako …/myapp/main/2.

Ostatní rodiny

Sady jsou nejstarší dveře; produkt jich pod /api/v1 vyrostl mnohem víc a mluví jimi CLI, MCP endpoint i prohlížeč. Každá rodina stránkuje — nic nečte celý projekt. Zápisy na nástěnku se připisují jako výše; zápisy do enginu úkolů zaznamenávají jen ověřenou identitu — štítek X-Board-Actor se nikdy nestane aktérem v ledgeru.

Rodina	Co nese
`boards/{slug}`	Nástěnka samotná: karty, rozložení, hromadné úpravy, živé události přes SSE a WebSocket, nahrávání, importy, členové, zprávy, tahy, hrany a `undo`.
`cards/{id}`	Jedna karta: obsah elementu, soubor, tvář, verze, obnova, OCR, `set-map`, kterou definují elementy `ref`.
`annotations/{id}`	Drát pracovní fronty: kapsle, zprávy, refy, snapshot, značení, revize, pokusy, uvolnění a zrušení a dveře, které založí úkol.
`boards/{slug}/annotations/batch` · `…/agent-verdict`	Nálezy autorované agentem: dávkové dveře založí až 100 nativních anotací (rodí se jako `staged`, oblasti v pixelech zdrojového obrázku deklarované `cardVersion`, idempotentní podle `key`, autor `agent:<runtime>` vedle ověřené identity) — MCP nástroj `annotate`; `agent-verdict` je lidské Přijmout / Zamítnout, agentům nikdy nevystavené. `boards/{slug}/cards/{cardId}/crop.png` odpovídá hlavičkami `X-Source-Width`, `X-Source-Height` a `X-Card-Version` — prostorem, ve kterém oblasti žijí.
`work` · `work/wait` · `work/listeners`	Drát anotační práce, který čtou `work watch` a `wait_for_work`, a leasy posluchačů.
`sessions/{id}`	Nahrané session: události, snímky, chunky, digest, rrweb, kroky a kanál živého párování.
`reports/{id}`	Reporty rekordéru z vkládaného widgetu: schválit, zamítnout, redigovat, povýšit.
`tasks` · `comments` · `rules` · `views` · `states`	Engine úkolů — níže.
`templates`	Registr šablon nástěnek, který čtou a zapisují `get_templates` a `save_template`.
`docs` · `artifact-docs`	Sjednocená reference, kterou čtou nástroj `docs` a `vitrinka docs`.
`diary` · `personal/{period}`	Denní nástěnky, na které posílá Snap, a jejich týdenní, měsíční a roční souhrny.
`boards/{slug}/cards/{id}.pdf` · `.eml` · `.docx`	Karta dokumentu jako soubor: PDF z vlastního vykreslovače nástěnky, koncept e-mailu s vloženými obrázky, dokument Wordu; `?audience=` ho filtruje.
`eve/{path}`	Proxy na AI backend — níže.

Engine úkolů

Úkoly mají id v rámci workspace a při výpisu se omezují na projekt. Výpis bere tentýž dokument filtru, který upravuje lišta filtrů v prohlížeči, ?f=<base64url json>, a stránkuje keyset kurzorem, který nese vlastní pořadí — kurzor z jednoho pořadí je v jiném odmítnut.

Endpoint	Co dělá
`GET /api/v1/projects/{project}/tasks`	Filtrovaný, seřazený, stránkovaný výpis; okna `created` a `updated` ve filtračním dokumentu zužují podle toho, kdy byl úkol založen a naposledy změněn. `?ask=<phrase>` nechá Evu přeložit větu do tohoto dokumentu a vrátí ho jako `compiled` — další stránka ho předá jako `f` spolu s kurzorem; bez AI backendu odpoví `503` a jmenuje dveře, které AI nepotřebují. Vedle něj také `states`, `labels`, `sprints`, `milestones`, `views`, `rules`, `intake`.
`POST /api/v1/tasks` · `PATCH /api/v1/tasks/{id}` · `DELETE /api/v1/tasks/{id}`	Založit, upravit, měkce smazat. `POST /api/v1/tasks/bulk` přesune mnoho naráz.
`POST /api/v1/tasks/{id}/rank`	Ruční pořadí — před jiný úkol nebo za něj.
`GET /api/v1/tasks/search`	Hledání seřazené podle relevance nad vším, co úkol nese (název, tělo, pole, odkazy, komentáře), napříč projekty nebo v jednom: bez ohledu na diakritiku, shoda v názvu předběhne ostatní, nejdřív všechna slova, pak kterékoli, překlep hledá i svou opravu; každý zásah říká, kde se shodl (`matchedIn`, `matchedLabel`, `corrected`). Zúžení přes `type`, `state`, `parent` a `epic` (v libovolné hloubce); filtr, který nic nepojmenovává, vrátí 400 s povolenými hodnotami a tou nejbližší. Úkol, který dotaz jmenuje číslem (`#12`, `vt-12`, `SHO-12`, `<workspace>/12`, jeho URL, samotné `12` jako celý dotaz), stojí v zásazích první, označený `pinned`. Jinak dotaz bez jediného slova o alespoň 3 znacích vrátí 422 s diagnózou. `compact=1` vrací jednořádkové zásahy, každý s `project`, když hledání přesahuje projekty. `GET /api/v1/tasks/{id}/search` hledá uvnitř jednoho úkolu a jeho podstromu — včetně polí, odkazů a komentářů.
`GET /api/v1/search`	Hledání napříč workspacem v jednom volání: `tasks`, `annotations` (podle čísla: `№432`), `pages`, `boards`, `tags`, `cards`, `sessions`, `shots`, každá skupina řazená a omezená zvlášť a vrátí se jen skupiny, které proběhly; najde se jakýkoli úryvek o třech a více znacích, i uprostřed slova; `project`, `type`, `state`, `tags` zužují a hodnota, která nic nepojmenovává, vrátí 400 s povolenými hodnotami a tou nejbližší; `totals` počítá vrácené zásahy. Úkoly a stránky nesou svou kanonickou `url`; úkol zapsaný jako `#12`, svým klíčem (`FIX-12`), `<workspace>/12` — i z jiného workspace, jehož jste členem — nebo svou URL se připne na začátek. `mode=resolve` čte `q` jako JEDEN odkaz na úkol (slova z názvu, id v jakémkoli zápisu, URL, větev, `bugs under <epic>`, `mine`) a vrací `verdict` (`exact`, `confident`, `ambiguous`, `none`), `interpreted`, nejvýš 5 kandidátů (`candidates`) s `parentId`, `childCount` a `why` a `next`.
`GET /api/v1/resolve`	Kořen platformy (také `/w/{slug}/api/v1/resolve`): `?url=` vložený odkaz → úkol, projekt, board nebo karta, kterou pojmenovává, v kterémkoli workspacu, jehož je uživatel členem; `foreign` vůči `?from=`. Jediná 404 pro cokoli, co uživatel nevidí.
`POST /api/v1/memory/resolve`	`recall --deep` nástroje memo (`vitrinka memory resolve`): `{query, scope, candidates, budget: {k}}` (≤ 40 kandidátů, jen názvy) → Evino pořadí `{ranked: [{id, rev, score, why}], dropped?}` jen z poslaných kandidátů v jejich revizích. Synchronní (7 s); odmítnuté pole vrátí 422 s jeho jménem, nedostupný backend 404 `not_configured`.
`POST /api/v1/projects/{project}/ask`	Jedna otázka běžnou řečí nad celým projektem, `{question, intent?, budget?}` — „co blokuje 4.0.0?“: Eve si přečte úkoly projektu a odpoví `{answer, tasks, confidence, intent, actor}`, každý úkol s `id`, `key`, `title`, `type`, `state`, `url` a `why`, jen živé úkoly toho projektu. Stojí AI kredity; bez AI backendu vrátí `404` a jako dveře, které ho nepotřebují, jmenuje `search`. `POST /api/v1/tasks/{id}/ask` se ptá nad korpusem jednoho úkolu a odpovídá s `citations`.
`GET /api/v1/tasks/{id}/comments` · `links` · `refs` · `events` · `runs`	Komentáře úkolu, typované vazby, připojené refy, jeho ledger a AI běhy nad ním.
`POST /api/v1/projects/{project}/intake`	Intake dveře — jediná cesta, jak se z návrhu stane draft. `POST /api/v1/tasks/{id}/intake` dá verdikt.
`POST /api/v1/projects/{project}/sprints/{id}/start` · `complete`	Životní cyklus sprintu; `complete` přenese nedokončenou práci.
`GET /api/v1/rules/schema` · `POST /api/v1/rules/{id}/dry-run`	JSON schéma dokumentu pravidla a přehrání nad nedávným ledgerem bez zápisu.
`GET /api/v1/me/work`	Stůl přihlášené identity napříč projekty: přiřazené, založené, zmíněné, po termínu.
`GET /api/v1/tasks/{id}/pickup` · `POST /api/v1/tasks/{id}/handback`	Dva konce pracovní smyčky — pracovní smyčka.
`POST /api/v1/tasks/{id}/complete`	Jediné dveře pro dokončení todo.
`POST /api/v1/projects/{project}/todos/fire` · `GET /api/v1/me/ripe`	Jediný vyhodnocovač typovaných podmínek todo — todo.
`POST /api/v1/tasks/{id}/run` · `GET /api/v1/projects/{project}/qa/runs`	Jediné dveře z manifestu runneru do záznamu QA (`vitrinka qa run`) a seznam běhů.
`GET /api/v1/projects/{project}/release` · `POST …/release/refresh` · `cut` · `notes`	Linka vydání: její okna a `docHeadSha` (head, pro který je stránka napsaná), průchod (`until` připíchne konec okna na commit), uzavření (`expectHead` odmítne posunuté okno), připojený dokument s poznámkami.
`/api/v1/projects/{project}/fields`	Definice vlastních polí.
`/api/v1/projects/{project}/work-time`	Události pracovního času, předpověď a export — pracovní čas.
`POST /api/v1/projects/{project}/deploys`	Zaznamená, že commit dorazil do prostředí, aby se spustila todo `deployed <env>`; produkční značka vrací svou `lineage` pro Historii.
`POST /api/v1/projects/{project}/memory/watches` · `GET …/memory/watches/completions`	Watch řádky memo `for: human` zrcadlené do JEDNOHO todo na řádek (`vitrinka memory watch put`) a todo dokončená tady, která čekají, až je memo zapíše jako hotová.
`POST /api/v1/projects/{project}/merge` · `transfer`	Sloučí projekt do jiného ve stejném workspace, nebo ho zkopíruje do jiného workspace, který vlastníte — jen vlastník workspace.
`PUT /api/v1/projects/{project}/mirror` · `POST /api/v1/projects/{project}/mirror/sync`	Navázat zrcadlo do Jiry (konektor, strana pravdy, mapa stavů) a spustit synchronizaci — jen správce.

Navázání zrcadla, spuštění synchronizace, psaní pravidel a zaznamenání nasazení jsou akce administrátora a sloučení nebo přesun projektu patří vlastníkovi workspace; všechno ostatní je na úrovni člena. Celý model je záložka Produkt.

Živé události

GET /api/v1/events je jeden proud Server-Sent Events na workspace — tatáž sběrnice, na které běží samotná aplikace v prohlížeči — takže skript může workspace sledovat, místo aby se dotazoval na výpisy. ?project= ho zúží na jeden projekt; ?kind= (opakovaně, nebo oddělené čárkami) vybírá z task, annotation, board, sidebar, favorites, workspace-settings, prefs, project, agenda a decision a neznámý druh je 400, která ho pojmenuje.

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

Každý rámec je id:, event: (druh) a data: — jeden řádek ledgeru s jeho kind, project, ref, actor, createdAt a typovaným obsahem data — a každých 25 sekund přijde ping v komentáři. Navážete hlavičkou Last-Event-ID, nebo ?after=<id>; bez kurzoru proud začne od aktuálního konce. Řádky jsou trvalé a drží se 30 dní, takže nové připojení po spánku nebo nasazení přehraje všechno, co zmeškalo. Ověřuje se jako každé volání /api/v1, včetně workspace.

Rámec decision sleduje Needs you (GET /api/v1/human/decisions): jedno rozhodnutí do něj přibylo nebo z něj odešlo, ať ho pohnuly jakékoli dveře — aplikace, CLI, MCP, předání agenta, pravidlo. Jeho ref je id rozhodnutí v gramatice toho čtení a data říkají, co se stalo:

{ "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" } }

Pole `data`	Význam
`op`	`raised` (teď čeká) · `resolved` (zodpovězeno: odškrtnutá brána, hotové todo, verdikt nad návrhem, zodpovězená otázka) · `withdrawn` (přestalo čekat bez odpovědi: odebráno, uzavřeno, smazáno, staženo, nástěnka archivována) · `changed` (dál čeká, ale změnila se jeho otázka nebo člověk, na kterého čeká)
`kind`	`gate` · `todo` · `intake` · `plan` · `ask` — tytéž druhy jako řádky toho čtení
`taskId`, `gate`	Úkol, na kterém brána, todo nebo návrh žije, a klíč brány pro `POST /api/v1/tasks/{id}/gates/resolve`
`verdict`	Verdikt nad návrhem: `accepted` · `declined` · `merged`
`board`, `question`, `count`	Nástěnka otázky, otázka, která se pohnula (`0`, když se archivovala nebo obnovila celá nástěnka), a kolik otevřených otázek ještě drží řádek nástěnky — `0` znamená, že řádek zmizel

Jediný řádek pojmenují jen gate:<task>:<handle> a todo:<task>: klient, který ho drží, ho při resolved nebo withdrawn může uzavřít. ask:<board> je složený řádek nástěnky, který zmizí až při count rovném 0; intake:<draft> jmenuje návrh (řádek jeho rodiny, jen když ji vede) a plan:<project>:<goal>:<day> den cíle, ke kterému tah patří (plný pokračuje na kartách :<part>), takže oba vždy čtou znovu. Stejně tak raised, changed a každý ref, který klient nedrží: jen Needs you ví, na koho rozhodnutí čeká a co složený řádek ještě drží. Rámec vidí ten, kdo smí vidět, čeho se týká: rozhodnutí úkolů celý workspace, otázky osobní nástěnky jen její vlastník. Todo, kterému s časem nastane termín, není zápis, a tedy ani rámec — Needs you ho najde při dalším čtení.

Reporty rekordéru a politika

Vkládaný widget reportů a rekordér v prohlížeči mluví se dvěma malými rodinami, které stránky QA popisují ze strany testera.

Endpoint	Co dělá
`POST /api/v1/reports` · `GET /api/v1/reports`	Report z widgetu `<vitrinka-report>` se založí rovnou, když jeho nahlašujícího podepsala hostitelská aplikace, jinak zůstane v karanténě; rrweb chunky a jejich události pod něj proudí, `submit` je jeho poslední volání a fronta review vypíše ty zadržené správcům.
`POST /api/v1/reports/{id}/approve` · `reject` · `redact` · `promote`	Schválení převede záznam na sezení a založí hlášení jako úkol v Inboxu. Propagace vytvoří nebo připojí externí tiket; při schválení se spouští automaticky jen se zapnutou volbou auto-ticket. Redakce odstraní zaznamenaná data po odeslání.
`GET /api/v1/report-config`	Nastavení projektu dostupné publikačnímu klíči widgetu. Klíč může také odesílat hlášení a jejich záznamy; nemůže číst frontu hlášení ke kontrole.
`GET` · `PUT /api/v1/recorder/policy`	Politika redakce, kterou uplatňují klienti zachytávání i serverová pojistka při příjmu — redakce.
`GET` · `PATCH /api/v1/recorder/me`	Vlastní záznam tokenu rekordéru, dostupný jen s tokenem `vkr_`: `kind` (`linked` nebo `key`), workspace, propojená osoba (u klíče vydaného adminem `null`), projekt klíče, popisek zařízení nebo název klíče a předvolby panelu rekordéru `prefs` (`size` a `verbose`) uložené na účtu osoby. PATCH slučuje `{"prefs":{…}}`; klíč vydaný adminem dostane `409`, jeho předvolby zůstávají v zařízení.

Identita, licence a verze

Endpoint	Co dělá
`GET /api/v1/whoami`	Kdo je přihlašovací údaj, v kterém workspace, s jakou rolí.
`GET /api/v1/version`	Verze serveru — příchozí maják, na který se ptají klienti; server nikdy nevolá domů.
`GET /api/v1/license`	Zda je instalace licencovaná a její `status` — `active`, `grace` nebo `expired`, bez licence prázdný. Zákazníka, tier a expiraci dostane navíc jen přihlášená relace v prohlížeči, token nikdy. Odpovídá i tehdy, když prošlá licence pozastaví zápisy, a každá odpověď licencované instalace nese stav v hlavičce `X-License-Status` — licence.
`GET /api/v1/audit`	Append-only auditní log, prohledávatelný správci — audit.

Proxy na AI backend

/api/v1/eve/{path} předává požadavky z konverzací projektu, úkolu a nástěnky nastavenému AI backendu. Rozhraní je protokol AI backendu, docs/ai-backend-protocol.md ve zdrojích serveru. Nastavení backendu ve workspace má přednost před AI_BACKEND_URL a AI_BACKEND_TOKEN. Požadavky měnící stav na spravovaném backendu vyžadují AI kredity; čtení a vlastní výpočetní prostředky workspace je nevyžadují.

OAuth pro MCP hosty

MCP hostitelé se připojují na /mcp (nebo /w/<workspace>/mcp) jako veřejní OAuth 2.1 klienti: authorization code s povinným PKCE, objevený z /.well-known/oauth-authorization-server a /.well-known/oauth-protected-resource (také s příponami /mcp a /w/<slug>/mcp); registrace dokumentem s metadaty client-ID nebo přes POST /oauth/register (pod AIR_GAP=1 jen to druhé); tok je GET a POST /oauth/authorize a POST /oauth/token, s rotujícími refresh tokeny. Grant má rozsah read nebo read write a dosáhne na workspace zaškrtnuté při souhlasu — výchozí jsou všechny týmové workspace vašich organizací včetně později vytvořených, Personal jen po zaškrtnutí — a později je upravíte v Nastavení → Připojené aplikace bez nového přihlášení. Jeho výchozí workspace dostane volání, která žádný nejmenují (MCP volání s projektem, který zná jen jeden jiný dosažitelný workspace, přistane tam; projekt známý ve více workspace server odmítne a vypíše každý zápis); každý další dosažitelný workspace je na dosah jednou hlavičkou nebo <workspace>/<project>; workspace mimo dosah odpoví 403 workspace_not_connected s odkazem manage_url. POST /oauth/revoke (RFC 7009) připojení vyřadí; uživatelé připojení odpojují a správci je ze svého workspace odebírají ve svých seznamech připojení — MCP pro libovolného klienta.

Na této stránce