Dokumentace

Kaloko

Stáhnout
Markdown s obrázky (.zip)Složka pro Docusaurus (.zip)Složka pro VitePress (.zip)Složka pro MkDocs (.zip)HTML pro offline čtení (.zip)PDFNovinky jako JSON
Stránky

API kondice pro dashboardy

Týdenní SEO průchod několika tisíci stránek skončí jako jeden běh se stovkami nálezů. Dashboard ho nechce stahovat a počítat znovu. Tyto adresy odpovídají už sečtenými čísly: po jazycích, krocích (krok stack je jedna šablona stránek), kontrolách nebo packech, se stránkami, kterých se problém týká nejvíc, a s tím, co se změnilo od běhu předtím.

Token pro dashboard

V Nastavení → API tokeny vytvořte token s rozsahem read:health (na Enterprise i jako servisní účet). Čte adresy z této stránky a zbytek kondice (GET …/health běhu, scénáře nebo projektu, MCP get_health); na všechno ostatní odpoví 403. Poslouží i token s rozsahem read.

curl -H "Authorization: Bearer $KALOKO_TOKEN" \
  "https://kaloko.app/api/v1/orgs/acme/scenarios/seo-weekly/latest/health/aggregate?by=locale,step"

Adresy

PožadavekCo vrátí
GET /api/v1/orgs/<org>/scenarios/<id>/latestNejnovější sdílený běh scénáře, který vidíte: id, datum, verdikt, počty kondice a odkazy níže. ?environment=production vybere nejnovější běh v jednom prostředí
GET …/scenarios/<id>/latest/health/aggregateSouhrn tohoto běhu jedním voláním
GET …/scenarios/<id>/latest/health/diffRozdíl tohoto běhu jedním voláním
GET /api/v1/orgs/<org>/runs/<run>/health/aggregatePočty po skupinách s nejvíc zasaženými stránkami a počty z rozdílu
GET /api/v1/orgs/<org>/runs/<run>/health/diffNové, opravené a pořád otevřené výsledky, každý s během, který ho viděl poprvé
GET /api/v1/orgs/<org>/scenarios/<id>/findingsOtevřené výsledky seskupené do nálezů podle kontroly, webu, jazyka a kroku, se stavem (níže)

MCP má totéž jako get_health_aggregate, get_health_diff (s run_id, nebo se scenario a environment) a list_findings.

Co se počítá

Jeden výsledek je jedna stránka v jednom jazyce pro jednu kontrolu. Stránka prošlá ve více viewportech se počítá jednou, s nejhorším verdiktem. Krok stack počítá každou svou stránku, obyčejný krok je stránkou sám. Výsledek je pass, fail, needs_review (hodnotitel si nebyl jistý) nebo not_evaluated. Kontroly, které se na stránku nevztahují, se nepočítají.

Kondice jen radí: tato čísla nikdy nezmění verdikt kroku ani běhu.

Souhrn

GET …/health/aggregate bere:

ParametrVýznam
byČárkami oddělené: locale, step, check, pack. Výchozí locale,step,check. Prázdné sečte vše do jedné skupiny
locale, step, check, packJen výsledky s touto hodnotou
topZasažené stránky na skupinu, 0 až 20 (výchozí 5); selhávající stránky před nejistými
limitSkupiny v odpovědi, 1 až 5000 (výchozí 500), nejvíc selhávající první
{
  "schema": "kaloko.health-aggregate.v1",
  "run": { "id": "2026-10-12-seo-weekly-a1b2c3", "scenario": "seo-weekly", "title": "Týdenní SEO", "project": "web", "environment": "production", "started_at": "2026-10-12T05:00:00.000Z", "canvas": "https://kaloko.app/acme/runs/2026-10-12-seo-weekly-a1b2c3/#health", "aggregate_url": "…", "diff_url": "…" },
  "by": ["locale", "step", "check"],
  "filter": {},
  "totals": { "results": 16800, "pass": 15910, "fail": 812, "needs_review": 64, "not_evaluated": 14, "pages": 2800 },
  "checks": { "HC112": { "text": "The page carries structured data (JSON-LD)", "pack": "seo", "level": "warning" } },
  "diff": { "previous": { "id": "2026-10-05-seo-weekly-d4e5f6", "started_at": "2026-10-05T05:00:00.000Z" }, "new": 14, "fixed": 3, "still_open": 859, "unchecked": 0, "worse": 1, "expired": 0, "open": 876 },
  "group_count": 168,
  "truncated": false,
  "groups": [
    {
      "id": "locale=pl;step=eshop;check=HC112",
      "locale": "pl", "step": "eshop", "check": "HC112",
      "results": 400,
      "counts": { "pass": 210, "fail": 190, "needs_review": 0, "not_evaluated": 0 },
      "affected": 190,
      "top": [
        { "step": "eshop", "locale": "pl", "check": "HC112", "page": "sklep-kubek", "path": "/pl/sklep/kubek", "url": "https://www.example.com/pl/sklep/kubek", "verdict": "fail", "evidence": "no JSON-LD block on the page" }
      ]
    }
  ]
}
  • id skupiny se skládá z jejích hodnot, takže stejná skupina má každý týden stejné id: použijte ho jako klíč v dashboardu.
  • affected je fail plus needs_review.
  • checks vyjmenuje každou kontrolu běhu s textem, packem a úrovní (error nebo warning, když selže).
  • diff je shrnutí rozdílu níže; previous je null u prvního běhu scénáře v daném prostředí.

Rozdíl

GET …/health/diff porovná výsledky, které selhávají nebo jsou nejisté, s tím, co měl scénář otevřené po svém předchozím sdíleném běhu ve stejném prostředí a projektu. Běhy stejného scénáře v jiném projektu se nikdy neporovnávají.

Výsledek je opravený (fixed), jen když ho tento běh zkontroloval a prošel. Výsledek, který tento běh nezkontroloval, zůstává otevřený a je v seznamu nezkontrolované (unchecked): stránka mimo tento týdenní výběr (rotate), vynechaný jazyk, kontrola, o které hodnotitel nedokázal rozhodnout. Drží si first_seen a rozhodne další běh, který ho zkontroluje. Výsledek, který 8 běhů po sobě nebo 60 dní nikdo nezkontroloval, vypadne: naposledy se objeví s "expired": true a započítá se do expired.

ParametrVýznam
statenew, fixed, still_open nebo unchecked; bez něj všechny čtyři seznamy
locale, step, check, packJen výsledky s touto hodnotou
limit, offsetStránkování v každém seznamu: nejvýš 2000 (výchozí 200)
{
  "schema": "kaloko.health-diff.v1",
  "run": { "id": "2026-10-12-seo-weekly-a1b2c3", "…": "…" },
  "previous": { "id": "2026-10-05-seo-weekly-d4e5f6", "started_at": "2026-10-05T05:00:00.000Z" },
  "counts": { "new": 14, "fixed": 3, "still_open": 859, "unchecked": 0, "worse": 1, "expired": 0 },
  "open": 876,
  "truncated": false,
  "new": {
    "total": 14,
    "items": [
      { "id": "eshop|pl|HC112|sklep-kubek", "step": "eshop", "locale": "pl", "check": "HC112", "page": "sklep-kubek", "url": "https://www.example.com/pl/sklep/kubek", "severity": "warning", "text": "The page carries structured data (JSON-LD)", "first_seen": { "run": "2026-10-12-seo-weekly-a1b2c3", "at": "2026-10-12T05:00:00.000Z" } }
    ]
  },
  "fixed": { "total": 3, "items": [] },
  "still_open": { "total": 859, "items": [] },
  "unchecked": { "total": 0, "items": [] }
}
  • id výsledku je step|locale|check|page. Zůstává stejné, dokud krok, jazyk, kontrola a stránka drží svá id, takže jednu stránku sledujete týden po týdnu. U obyčejného kroku je page null.
  • severity je error nebo warning u selhávající kontroly a info, když si hodnotitel nebyl jistý. Pořád otevřený výsledek, kterému se závažnost změnila, má ve was tu předchozí; worse počítá ty, které se zhoršily.
  • first_seen je běh, ve kterém výsledek začal selhávat a od té doby v žádném běhu neprošel. Výsledek, který byl opravený a vrátil se, začíná znovu.
  • open počítá, co je po tomto běhu otevřené: co teď selhává nebo je nejisté, plus nezkontrolované.
  • Web s víc než 50 000 otevřenými výsledky v jednom běhu si nechá 50 000 nejhorších a řekne truncated: true; zbytek se počítá jako nezkontrolovaný, nikdy jako opravený.

Nálezy

Osm set selhávajících stránek bývá tucet problémů: jedné šabloně v jednom jazyce chybí strukturovaná data. GET /api/v1/orgs/<org>/scenarios/<id>/findings seskupí, co má scénář otevřené, do nálezů: jedna kontrola na jednom webu v jednom jazyce na jednom kroku. Otisk (fingerprint) je check|site|locale|step, kde web je origin URL stránky (https://www.example.com). Týden po týdnu zůstává stejný, takže nález se počítá, rozhoduje a sleduje jednou, ať zasáhne kolik chce stránek. Nálezy čte i token read:health (MCP list_findings).

ParametrVýznam
environmentProstředí; bez něj nejnovější se zaznamenanou kondicí
locale, step, checkJen nálezy s touto hodnotou
statusopen, acknowledged, ignored nebo fixed
limit, offsetStránkování: nejvýš 1000 (výchozí 200)
{
  "schema": "kaloko.health-findings.v1",
  "scenario": "seo-weekly", "project": "web", "environment": "production",
  "run": { "id": "2026-10-12-seo-weekly-a1b2c3", "started_at": "2026-10-12T05:00:00.000Z", "canvas": "…" },
  "page": "https://kaloko.app/acme/health/seo-weekly?environment=production",
  "counts": { "open": 9, "acknowledged": 2, "ignored": 1, "fixed": 3 },
  "filter": {}, "total": 15, "offset": 0, "limit": 200,
  "findings": [
    {
      "id": "5f0c2a9e1b7d4c33",
      "fingerprint": "HC112|https://www.example.com|pl|eshop",
      "check": "HC112", "text": "The page carries structured data (JSON-LD)", "pack": "seo",
      "site": "https://www.example.com", "locale": "pl", "step": "eshop",
      "severity": "warning", "status": "acknowledged", "reason": null,
      "status_by": "jana@example.com", "status_at": "2026-10-12T09:14:00.000Z",
      "count": 190, "unchecked": 0, "fixed": 4,
      "samples": [
        { "page": "sklep-kubek", "url": "https://www.example.com/pl/sklep/kubek", "edit_url": "https://cms.example.com/pages/812/edit" }
      ],
      "first_seen": { "run": "2026-09-28-seo-weekly-77aa01", "at": "2026-09-28T05:00:00.000Z" },
      "last_seen": { "run": "2026-10-12-seo-weekly-a1b2c3", "at": "2026-10-12T05:00:00.000Z" },
      "issue": { "tracker": "jira", "key": "WEB-412", "url": "https://acme.atlassian.net/browse/WEB-412", "state": "open" }
    }
  ]
}
  • id je krátký hash otisku; používejte ho v odkazech a v PATCH.
  • severity je nejhorší z výsledků nálezu; count je počet stránek, kterých se teď týká. unchecked počítá stránky, které nejnovější běh nezkontroloval (zůstávají otevřené), fixed stránky, které nejnovější běh opravil.
  • samples ukáže až 10 stránek s edit_url, které uvádí jejich položka stacku, takže obsahový tým jde rovnou do CMS (Najděte, co na webu selhává).
  • first_seen je nejstarší první výskyt z jeho výsledků. last_seen je nejnovější běh, který ho zkontroloval a pořád selhával; u opraveného nálezu je to běh před opravou.
  • status je fixed, jakmile žádná jeho stránka neselhává; jinak to, co nastavil člověk (acknowledged, ignored s důvodem v reason), nebo open. Rozhodnutí patří k otisku: ignorovaný nález, který se vrátí, zůstává ignorovaný.
  • Když má stack traffic: (Opravte nejdřív stránky, které lidé opravdu vidí), má nález traffic (clicks a impressions sečtené přes jeho stránky, které čísla mají, a kolik těch stránek je, pages) a impact a každá ukázková stránka svoje traffic. Bez dat o návštěvnosti tam žádný z klíčů není.
  • issue.key je WEB-412 v Jiře nebo Linearu, acme/website#87 na GitHubu a MKT-12 v Plane.
  • Nálezy jdou od nejhoršího, opravené na konci.

Nález potvrdíte nebo ignorujete přes PATCH …/scenarios/<id>/findings/<nález>[?environment=] s { "status": "acknowledged" }, { "status": "ignored", "reason": "Starý blog, v listopadu se stěhuje do nového CMS" } nebo { "status": "open" }. Smí to každý, kdo smí komentovat běhy scénáře; token potřebuje rozsah comment (token read:health nic nemění). Stejnou tabulku ukazuje aplikace v Kondice → Nálezy u každého scénáře, s tlačítky pro tytéž tři možnosti.

Issues k nálezům

Scénář může pro každý nový nález založit issue v Jiře, Linearu, GitHub Issues nebo Plane. Zapíná to Developer / Tester přes PUT …/scenarios/<id>/findings/sync:

{ "tracker": "jira", "min_severity": "error", "environment": "production" }

V Jiře a Linearu jde issue do projektu nebo týmu, na který je projekt scénáře namapovaný v Nastavení → Integrace (Propojte trackery a kanály). U GitHubu a Plane je cíl přímo v nastavení a routes pošlou část nálezů do jiného trackeru než zbytek scénáře:

{
  "tracker": "github", "min_severity": "warning",
  "github": { "repository": "acme/website", "labels": ["seo"], "assignee": "jana" },
  "plane": { "project": "MKT", "labels": ["content"] },
  "routes": [{ "tracker": "plane", "checks": ["HC127", "HC9*"], "packs": ["aeo"] }]
}
  • github: repozitář (owner/repo), štítky a volitelně komu issue přiřadit. Kaloko issue založí jako aplikace Kaloko na GitHubu, když je na repozitáři nainstalovaná a má oprávnění Issues; jinak fine-grained tokenem, který připojil admin (Issues: read and write na ten repozitář).
  • plane: identifikátor projektu (MKT) a štítky, které v projektu už existují.
  • Repozitář i projekt v Plane musí být na seznamu, který pro projekt scénáře povolil admin organizace v Nastavení → Integrace (projekt bez vlastního řádku použije výchozí). Cokoli jiného Kaloko odmítne s 403 dřív, než se zeptá GitHubu nebo Plane, takže odpověď neprozradí, jestli to existuje. Když admin cíl ze seznamu odebere, nová issues tam už nepůjdou; ta existující Kaloko sleduje dál.
  • routes: nejvýš 20, v pořadí. Rozhodne první cesta, která jmenuje kontrolu nálezu (HC127, nebo začátek jako HC1*) nebo jeho balíček (seo, aeo…); všechny ostatní nálezy jdou do tracker. Každý tracker z cest musí být připojený. Když se cesty změní, existující issue zůstane, kde je, a Kaloko ho sleduje tam.

Při uložení Kaloko u trackeru ověří repozitář, přiřazeného člověka, projekt i štítky a řekne, co nesedí.

Po každém sdíleném běhu scénáře Kaloko založí jedno issue na každý nový nález se závažností aspoň min_severity (error, warning nebo info), nikdy dvě pro jeden otisk a žádné pro ignorovaný. Issue říká, která kontrola kde selhává, na kolika stránkách, ukáže až deset z nich s odkazy na úpravu a s traffic: i kliknutí a zobrazení každé stránky a celého nálezu s jeho dopadem; odkazuje zpět na nález. Když se počet zasažených stránek změní aspoň o tři a o čtvrtinu, issue dostane komentář; když je nález opravený, komentář a issue se zavře (Jira: první přechod do Done; Linear: první dokončený stav týmu; GitHub: zavřené jako dokončené; Plane: první dokončený stav projektu). Když se vrátí, totéž issue dostane komentář a znovu se otevře, pokud to tracker dovolí (Plane: první stav k zahájení).

Jeden běh založí nejvýš 20 issues, nejhorší první, a do trackerů zavolá nejvýš 60krát během 20 sekund, z toho nejvýš 25 požadavků do Plane, počítá se každý (jeho API bere 60 za minutu; zavření issue navíc jednou za běh načte stavy projektu); zbytek přijde s dalším během. Nález, který tracker odmítne (třeba kvůli poli, které nebere), si chybu nechá v seznamu a ostatní pokračují. Když tracker odmítne spojení, chce zpomalit nebo neodpovídá, běh pro ten tracker skončí a zkusí to další běh; nálezy pro jiný tracker pokračují. Založení, které se do trackeru vůbec nedostalo (spojení nešlo obnovit, tým v Linearu neexistuje, adresa Plane je odmítnutá), zkusí nález znovu s dalším během. Když tracker jasně neřekne, jestli issue založil (vypršel čas nebo chyba serveru), nález ukazuje issue jako zakládané s důvodem v issue.error a Kaloko druhé nezaloží: podívejte se do trackeru, a když tam nic není, zvolte u nálezu na stránce nálezů Zkusit znovu (jde to, až issue čeká dvě minuty), nebo pošlete POST …/scenarios/<id>/findings/<finding>/retry[?environment=] (Developer / Tester); další běh ho založí. Zakládání visící déle než hodinu uvolní i uložení nastavení.

Nastavení patří ke scénáři v jeho projektu: když scénář přesunete do jiného projektu, issues přestane zakládat, dokud je tam někdo nezapne. { "tracker": null } synchronizaci vypne; GET na stejné adrese ukáže nastavení a trackery, do kterých organizace může nálezy posílat.

Běhy sdílené dřív

Počty běhu vzniknou jednou, po jeho sdílení. Běh sdílený dřív, než toto API existovalo, se spočítá při každém dotazu, což u velkého běhu může pár sekund trvat; jeho rozdíl ho porovná s během před ním a řekne "recorded": false. První běh sdílený potom začne historii svého scénáře.

Když se něco změní

Webhook health.changed pošle počty z rozdílu a první nové a opravené výsledky po každém sdíleném běhu, ve kterém se něco pohnulo: Webhooky.

Na této stránceNa této stránce