API, CLI a MCP pre Fukamo audit

ZAČNITE TU

Prvá požiadavka

# 1. Start the full audit: 202 with an id (a refusal is printed and ends the script)
curl -sS -X POST 'https://fukamo.com/api/v1/audits' \
  -H "Authorization: Bearer $FUKAMO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"urls": ["https://example.com/"]}' > start.json
ID=$(jq -r '.id // empty' start.json)
[ -n "$ID" ] || { cat start.json; exit 1; }

# 2. Poll every 5 seconds until it is complete (typically 1–4 minutes, at most 15)
for i in $(seq 180); do
  curl -sS "https://fukamo.com/api/v1/audits/$ID" -H "Authorization: Bearer $FUKAMO_API_KEY" > audit.json
  [ "$(jq -r .status audit.json)" = complete ] && break
  jq -e '.code and .code != "rate_limited"' audit.json > /dev/null && { cat audit.json; exit 1; }
  sleep 5
done

jq '.pages[0].result.score' audit.json

Vzorové dáta. Nič sa neodosiela a kľúč nepotrebujete.

OVERENIE KĽÚČA

Otestujte svoj API kľúč

Kľúč ide len na náš server a nikde sa neuloží. Test nespustí audit ani nemíňa kvótu.

Takto vyzerá odpoveď pre platný kľúč

HTTP/1.1 404 Not Found
{
  "error": "No such batch for this key.",
  "code": "not_found"
}

AKO TO FUNGUJE

Spustíte, pýtate sa, prevezmete

Audit trvá minúty, preto API hneď vráti id a výsledok si vyzdvihnete, keď je hotový.

POST /api/v1/audits1. Spustite audit
Pošlite URL. Server hneď odpovie 202 s id.
GET /api/v1/audits/{id}2. Pýtajte sa na stav
Každých 5 sekúnd, kým nie je status complete. Kvótu nemíňa.
GET /api/v1/audits/{id}?format=pdf3. Prevezmite výsledok
pages[].result nesie skóre a nálezy, ?format=pdf vráti PDF.

queuedčaká vo fronte

runningaudit beží, zvyčajne 1–4 minúty

completevýsledok je pripravený

Kľúč a limity

Kľúč posielajte pri každom volaní: Authorization: Bearer fk_… alebo X-Api-Key. Nikdy ho nedávajte do URL ani do verejného JavaScriptu.

Limit	Hodnota
Audity na kľúč	Predvolene 60 za hodinu
Plný audit jednej stránky	5 auditov z kvóty — predvolene 12 plných auditov za hodinu
Stránky jedného webu	1 za deň na kľúč, ak prevádzkovateľ kľúču nepovolil viac (najviac 50); tú istú stránku môžete auditovať znova
Rozbehnuté stránky na kľúč	Najviac 10 naraz, vo fronte alebo v behu
Dotazy na stav	120 za minútu, mimo kvóty
PDF reporty	Štvrtina kvóty, predvolene 15 za hodinu, oddelene od auditov

Kľúč získate na support@fukamo.com — napíšte, na čo ho použijete.

POST /api/v1/audits

Pošlite url. Voliteľne pridajte query: frázu, na ktorú sa stránka meria (jedna fráza, max. 32 slov).

Bez query: použije sa prvý návrh kľúčového slova z webu. Nálezy k nemu prídu ako review a skóre neznížia.
S query: hodnotí sa presne ako na webe. Stránka, ktorá frázu takmer nepokrýva, má obmedzené score.fukamo.
locale: jazyk reportu — en (predvolený), sk alebo es — pre JSON aj PDF.

curl -X POST "https://fukamo.com/api/v1/audits" \
  -H "Authorization: Bearer $FUKAMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/"], "query": "seo audit" }'

Hneď dostanete 202 s id a statusUrl. Kvóta sa míňa, až keď stránka odpovie — nedostupná stránka vráti 502 unreachable a nestojí nič.

{
  "version": 1,
  "id": "c547d6c0-15b5-4ba9-badc-c6fc392e0d7b",
  "status": "queued",
  "pages": 1,
  "queries": [
    { "url": "https://example.com/", "query": { "primary": "seo audit", "source": "input" } }
  ],
  "statusUrl": "/api/v1/audits/c547d6c0-15b5-4ba9-badc-c6fc392e0d7b"
}

curl "https://fukamo.com/api/v1/audits/<id>" -H "Authorization: Bearer $FUKAMO_API_KEY"

{
  "version": 1,
  "id": "c547d6c0-15b5-4ba9-badc-c6fc392e0d7b",
  "status": "complete",
  "createdAt": "2026-09-24T08:12:03.000Z",
  "queue": { "position": 0, "pagesAhead": 0, "etaSeconds": 0, "samples": 12 },
  "pages": [
    {
      "url": "https://example.com/",
      "status": "done",
      "result": {
        "version": 1,
        "url": "https://example.com/",
        "scannedAt": "2026-09-24T08:14:41.000Z",
        "score": {
          "seo": 71,
          "geo": 64,
          "fukamo": 68,
          "parts": { "content": 66, "google": 71, "ai": 64, "technical": 76,
            "experience": 61 },
          "html": 69
        },
        "summary": { "failed": 1, "review": 0, "extras": 0, "passed": 311,
          "notApplicable": 424, "unavailable": 6, "total": 742, "checksEvaluated": 760 },
        "findings": [
          { "id": "meta-description", "label": "Meta description is missing", "status": "fail",
            "level": "high", "category": "on-page",
            "evidence": "<head> does not contain <meta name=\"description\">",
            "fix": "Add a specific description of the page content." }
        ],
        "performance": {
          "mobile": { "performance": 0.62, "accessibility": 0.91, "seo": 1 },
          "desktop": { "performance": 0.88, "accessibility": 0.91, "seo": 1 }
        },
        "query": { "primary": "seo audit", "source": "input", "score": 62,
          "suggestions": ["seo audit", "website audit", "technical seo check"] },
        "unmeasured": ["JavaScript audit"],
        "reportUrl": "https://fukamo.com/?url=https%3A%2F%2Fexample.com%2F",
        "page": {
          "title": "Example — SEO audit", "description": "…", "language": "en",
          "canonical": "https://example.com/", "responseTimeMs": 312,
          "wordCount": { "main": 144, "total": 881, "pageType": "homepage" }
        }
      }
    }
  ],
  "site": { "addresses": 1, "uniquePages": 1, "meanScore": 68, "score": 68, "cappedBy": null,
    "issues": [] }
}

Pole	Význam
`score.fukamo`	Hlavné skóre, ako na webe a v PDF. Vážený priemer `score.parts`: obsah má najväčšiu váhu a skóre nemôže byť o viac ako 15 bodov nad ním.
`score.parts.content`	Obsah: rozsah, štruktúra, zhoda s frázou, aktuálnosť a dôveryhodnosť. Body sa získavajú, nielen strácajú.
`score.seo`, `score.geo`	Skóre HTML pre SEO a GEO.
`score.html`	Celkové HTML skóre, s meraniami.
`findings`	Len `fail` a `review`, od najhoršieho.
`summary`	Počty z webu, každý problém raz: `failed`, `review`, `extras` (technické doplnky), `passed`, `notApplicable` a `unavailable` dávajú spolu `total`. `checksEvaluated` sú všetky kontroly, ktoré bežali, pred zlúčením duplicít. Symptóm, ktorý spôsobuje iný nález, sa nepočíta ani nevypíše zvlášť; ostane len jeho príčina, ako na webe. Pravidlo z HTML a rovnaký audit Lighthouse (napríklad `image-alt`) sú jedna príčina: aj keď zlyhajú oba, `failed` ich započíta raz.
`query`	Meraná fráza a jej zdroj (`input`, `suggested`, `none`). `query.score` je zhoda, `query.suggestions` návrhy z webu.
`page`	Titulok, popis, jazyk, canonical, `responseTimeMs`, `wordCount`.
`performance`	Lighthouse pre mobil a desktop, 0–1. Chýba, ak PageSpeed zlyhal.
`unmeasured`	Čo nedobehlo. Taká časť skóre je `null` — nikdy 0.
`result.url`	Adresa po presmerovaní. `pages[].url` je tá, ktorú ste poslali.
`site.score`	Skóre webu. Nižšie ako `site.meanScore`, keď ho zastropuje problém celého webu (`site.cappedBy`).

Texty sú po anglicky, aj nálezy o fráze (query-*): slovenská fráza sa páruje podľa slovenských pravidiel a opisuje po anglicky. Citovaný obsah stránky ostáva v pôvodnom jazyku.
Napájajte sa na id, status a level — nikdy sa neprekladajú.
Nové polia môžu pribudnúť. Existujúce sa menia len s novou version.

?format=pdf vráti ten istý report ako PDF, po anglicky.

Ešte nie je hotový: 409 not_ready.
Limit: štvrtina kvóty kľúča (predvolene 15 za hodinu), oddelene od auditov.
Nad limit: 429 s retryAfter v sekundách.

curl -H "Authorization: Bearer $FUKAMO_API_KEY" \
  "https://fukamo.com/api/v1/audits/<id>?format=pdf" \
  -o report.pdf

Chyby

Chyby sú JSON s error a code. Rozhodujte sa podľa code, nie podľa textu.

429: počkajte retryAfter sekúnd.
502 / 503: skúste to znova niekoľkokrát, s rastúcou pauzou.

HTTP	code	Kedy
400	invalid_request	Telo nie je JSON s neprázdnym zoznamom `urls` verejných http(s) adries.
400	invalid_query	`query` nie je text alebo má viac než 32 slov.
400	invalid_locale	`locale` nie je `en`, `sk` ani `es`. Bez neho je report v angličtine.
400	bad_format	`?format=` je niečo iné než `json` alebo `pdf`.
400	bad_page	Pri `?format=pdf` nie je `?page=` index stránky v tomto audite.
401	unauthorized	Chýbajúci alebo neplatný kľúč — zámerne rovnaká odpoveď.
404	not_found	Audit s týmto id neexistuje alebo patrí inému kľúču.
409	not_ready	PDF sa pýta skôr, než je stránka hotová; nesie `status`. Počkajte na `complete`.
410	use_async	Starý synchrónny `GET /api/v1/audit` je vyradený. Použite `POST /api/v1/audits` a aktualizujte `@fukamo/cli` a `@fukamo/mcp` na 0.3.0 alebo novšiu.
429	rate_limited	Kvóta vyčerpaná, príliš veľa PDF, príliš veľa nedostupných cieľov (10 za hodinu) alebo príliš časté dotazy na stav; `retryAfter` v sekundách.
429	queue_full	Kľúč už má 10 stránok vo fronte alebo v behu; `retryAfter` v sekundách. Najprv si prevezmite ich výsledky.
429	domain_limit	Tento kľúč dnes už auditoval toľko stránok toho istého webu, koľko mu dovoľuje (predvolene 1, vlastník ho môže v administrácii zvýšiť); `availableUrl` je stránka, ktorú môže auditovať znova, `pagesPerSite` jeho denný počet.
502	report_failed	PDF sa nepodarilo vykresliť; JSON výsledok platí ďalej.
502	unreachable	Cieľ sa nedá auditovať (neexistuje, odmieta spojenie, nie je verejný). S `host`.
503	unavailable	Audit sa nepodarilo zaradiť do fronty pre chybu na našej strane; `retryAfter` v sekundách.
503	not_configured	Na serveri nie je vydaný žiadny kľúč.

Postman

Všetky volania z tejto stránky na import. V Postmane: Import → oba súbory → prostredie „Fukamo — produkcia“ → kľúč do apiKey. Súbory kľúč neobsahujú.

Stiahnuť kolekciu ↓Stiahnuť prostredie ↓

CLI — @fukamo/cli

export FUKAMO_API_KEY=fk_…          # from the environment, never as an argument
npx @fukamo/cli audit https://example.com/
npx @fukamo/cli audit https://example.com/ --query "seo audit" --json
npx @fukamo/cli audit https://example.com/ --pdf report.pdf

Spustí plný audit a počká (1–4 minúty). Vypíše skóre a 10 najhorších nálezov; --json vypíše presný result.
--query nastaví frázu. --pdf report.pdf uloží PDF.
Exit kód: 2 = chybné kontroly, 0 = žiadne, 1 = volanie zlyhalo. fukamo audit "$URL" && deploy tak funguje v CI.
S --pdf je exit kód 0, keď sa súbor zapíše — v CI hodnoťte cez --json.
fukamo result <id> vyzdvihne bežiaci audit bez spustenia nového.
Potrebuje Node 20+. FUKAMO_API_URL prepne server.
Verzie pod 0.3.0 dostanú 410 use_async — aktualizujte.

MCP — @fukamo/mcp

audit_website(url, query?) spustí audit a vráti skóre a chybné kontroly, každú s opravou.
Nie je hotový do 45 s? Dostanete id auditu a get_audit_result(audit_id) naň počká zadarmo.
fukamo_report_pdf(path, url | audit_id, query?) uloží PDF.

{
  "mcpServers": {
    "fukamo": {
      "command": "npx",
      "args": ["-y", "@fukamo/mcp"],
      "env": { "FUKAMO_API_KEY": "fk_…" }
    }
  }
}

Kľúč patrí do env, nikdy nie do promptu.

Čo si ukladáme

Pri každom audite, 90 dní: názov kľúča, čas, adresu auditovanej stránky (bez „?…“), id auditu, stav a trvanie. Kľúč nikdy, len jeho odtlačok.
Výsledok auditu ostáva na serveri pod svojím id. Zatiaľ sa automaticky nemaže.
Len verejné http(s) adresy; interné siete sú odmietnuté.