Blck Alpaca API a zdroje pre vývojárov
Všetko, čo táto stránka ponúka strojovo čitateľne: OpenAPI špecifikácia, Markdown varianty obsahu, llms.txt. Bez registrácie, bez kľúčov.
Čo to je a čo nie
Tieto endpointy obsluhujú formuláre a vyhľadávanie tejto stránky. Nie sú produktovým API. Nie je sa s čím integrovať, žiadny účet, žiadna záruka dostupnosti.
Dokumentované sú napriek tomu z jediného dôvodu: kto číta stránku automatizovane, nemá endpointy rekonštruovať z frontend kódu. A kto narazí na limit, má vopred vedieť, kde leží.
Interné endpointy v špecifikácii zámerne nie sú: invalidácia cache, mapa presmerovaní, polia spam filtra.
Zdroje
Pevné URL. Nemenia sa.
| URL | Účel |
|---|---|
| /mcp | MCP server pre knowledge base a kontrolu webových stránok. Streamable HTTP, revízia 2026-07-28 a 2025-11-25 nadol, iba POST. |
| /openapi.json | OpenAPI 3.1, JSON. Všetky verejné endpointy so schémami, operationId a chybovými kódmi. |
| /api/openapi.yaml | Tá istá špecifikácia ako YAML. |
| /llms.txt | Štruktúra stránky v próze: služby, knowledge base, štúdie, pre každý jazyk. |
| /llms-full.txt | Dlhá verzia s obsahom, nie iba zoznam odkazov. |
| /sitemap-index.xml | Úplný zoznam URL, rozdelený na časti. |
| /feed.xml | RSS blogových príspevkov. |
| /robots.txt | Pravidlá pre crawlerov vrátane content signal (ai-train=no). |
Autentifikácia
Žiadna. Verejné endpointy nemajú kľúče, tokeny ani účty.
Dva sa napriek tomu nedajú rozumne skriptovať: kontaktný formulár a SEO audit vyžadujú token, ktorý vytvorí až stránka v prehliadači. Špecifikácia ich označuje ako browser-only. Odpoveď 200 tam navyše neznamená, že požiadavka bola spracovaná. Požiadavky vyhodnotené ako automatizované dostanú rovnakú odpoveď ako skutočné.
Kvóty
Endpointy s limitom zverejňujú svoj stav v každej odpovedi, nielen pri 429. Kto číta hlavičky, nemusí naraziť, aby limit spoznal.
Posielajú sa dva formáty naraz: RateLimit a RateLimit-Policy podľa IETF návrhu draft-ietf-httpapi-ratelimit-headers-11, plus staršie hlavičky RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset, ktoré číta väčšina klientskych knižníc. K augustu 2026 návrh nie je RFC.
Ak platí viac kvót, napríklad pri chate na IP aj na reláciu, prvé dve hlavičky uvedú všetky. Staršie uvedú len tú najtesnejšiu.
Hlavičky odpovede pri volaní chatu
RateLimit-Policy: "chat-ip";q=50;w=86400, "chat-session";q=20;w=86400
RateLimit: "chat-ip";r=49;t=86399, "chat-session";r=19;t=86399
RateLimit-Limit: 20
RateLimit-Remaining: 19
RateLimit-Reset: 86399- q
- Povolené požiadavky v okne.
- w
- Dĺžka okna v sekundách.
- r
- Koľko ešte zostáva.
- t
- Sekundy do resetu. Rozdiel, nie časová značka.
MCP server
Knowledge base a kontrola webových stránok sú dostupné aj ako MCP server na POST /mcp. Asistent, ktorý ho pripojí, prehľadáva články, načíta plné texty bez parsovania HTML a kontroluje verejné webové stránky z hľadiska pripravenosti pre AI agentov.
Transport je Streamable HTTP. Endpoint obsluhuje dve generácie protokolu na tej istej URL. Revízia 2026-07-28 zbavila jadro stavu: žiadny initialize handshake, žiadne ID relácie, žiadny GET endpoint. Každá požiadavka je samostatný POST a nesie verziu protokolu v hlavičke MCP-Protocol-Version. Povinná je Mcp-Method a pri tools/call aj Mcp-Name; ak sa hlavičky nezhodujú s telom, požiadavka sa odmietne.
Klienti na 2025-11-25, 2025-06-18 alebo 2025-03-26 namiesto toho začínajú s initialize a nové hlavičky vynechajú. Oficiálne SDK je vo verzii 1.30.0 stále na 2025-11-25, takže dnes je to bežnejšia cesta. Ani tam nevzniká relácia: server nevydáva Mcp-Session-Id a každý POST stojí sám za seba. Verzia, ktorá nie je ani na jednom zozname, sa odmietne s -32022 a so zoznamom podporovaných revízií.
Bez registrácie. Platí tá istá kvóta ako pri ostatných endpointoch a obsah sa smie použiť s uvedením zdroja.
| Nástroj | Popis |
|---|---|
| search_knowledge_base | Fulltextové vyhľadávanie v názve, krátkej definícii a hlavnom kľúčovom slove článkov knowledge base Blck Alpaca (SEO, GEO, AI agenti, marketingová automatizácia). Vracia zhody s URL a trojicou ciest; plný text načíta get_knowledge_article. |
| list_knowledge_categories | Vráti štruktúru knowledge base: všetky kategórie s ich témami, každú so slugom a URL. Vstupný bod, keď nie je známy vyhľadávací výraz. |
| list_knowledge_topic_articles | Všetky publikované články jednej témy. Slug kategórie a témy si musia zodpovedať a pochádzať z rovnakého jazyka; ak nie, odpoveď uvedie prečo. |
| get_knowledge_article | Plný text článku knowledge base ako Markdown, k tomu krátka definícia, kľúčové body, doložené štatistiky so zdrojom a FAQ. Trojica ciest pochádza zo search_knowledge_base alebo list_knowledge_topic_articles. |
| audit_website | Skontroluje verejnú webovú stránku z hľadiska pripravenosti pre AI agentov a GEO: dokážu ju AI agenti nájsť, prečítať, pochopiť a pracovať s ňou? Načíta stránku tak ako agent (iba GET, bez prihlásenia, bez zmien) a hodnotí päť oblastí. Vráti celkové skóre, skóre oblastí, tri najúčinnejšie zistenia s príslušným návodom, všetky jednotlivé kontroly a odkaz na úplnú správu. Nejde o právne posúdenie. |
Vypísať nástroje
curl -X POST "https://blckalpaca.at/mcp" \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/list" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Uvedený v Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base
Pripojenie v tvojom AI asistentovi
Jedna adresa pre všetkých: https://blckalpaca.at/mcp, bez registrácie a bez kľúča. Potom máš v asistentovi k dispozícii nástroje knowledge base a kontrolu webových stránok (audit_website).
Cesty v menu pochádzajú z dokumentácie poskytovateľov, stav október 2026. Ak poskytovateľ zmení rozhranie, platí jeho dokumentácia.
Claude (web a desktop)
- Otvor Customize → Connectors, klikni na „+ Add“ a potom na „Add custom connector“.
- Ako názov zadaj „Blck Alpaca“ a ako URL https://blckalpaca.at/mcp, dvakrát potvrď tlačidlom „Continue“ a dokonči tlačidlom „Add“. Autentifikácia nie je potrebná.
- V chate cez „+“ → „Connectors“ zapni prepínač pri Blck Alpaca.
Dostupné vo všetkých plánoch, v pláne Free je povolený jeden vlastný konektor. V Team a Enterprise ho najprv pridá Owner v Organization settings → Connectors.
Claude Code
claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp- Spusti v termináli. V relácii príkaz /mcp ukáže, či je spojenie aktívne.
ChatGPT
- V ChatGPT Plugins klikni na „+“ a potom na „Add custom MCP server“.
- Zadaj názov a popis, v časti „Connection“ uveď URL https://blckalpaca.at/mcp, zvoľ bez autentifikácie a dokonči tlačidlom „Create as a plugin“.
- V chate napíš „@“ a vyber Blck Alpaca.
Perplexity
- V nastaveniach účtu otvor „Connectors“, klikni na „+ Custom connector“ a zvoľ „Remote“.
- Zadaj názov a URL https://blckalpaca.at/mcp, autentifikácia „None“.
Pre účty Pro, Max a Enterprise. V Enterprise musí vlastné konektory najprv povoliť admin.
Grok
- Otvor grok.com/connectors, zvoľ „New Connector“ a potom „Custom“.
- Zadaj URL https://blckalpaca.at/mcp. Grok nástroje rozpozná sám a použije ich, keď k nim otázka sedí.
V Grok Business a Enterprise konektor najprv pridá admin v konzole xAI.
Gemini CLI
gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp- Spusti v termináli. Bez „-s user“ platí záznam len pre aktuálny projekt. V relácii príkaz /mcp ukáže stav.
Ak si settings.json upravuješ sám: záznam v mcpServers potrebuje „httpUrl“, nie „url“. „url“ je určené pre starý transport SSE.
Iní klienti
- Funguje každý klient so Streamable HTTP: typ servera HTTP, adresa https://blckalpaca.at/mcp, bez hlavičiek. Klienti, ktorí ovládajú len starý transport SSE, nie sú podporovaní.
Riešenie problémov
Najčastejšie prekážky pri pripájaní, s príčinou a riešením.
- Asistent hlási, že nastavenie zlyhalo.
- Server komunikuje len cez Streamable HTTP metódou POST, od revízie MCP 2025-03-26. Klienti, ktorí očakávajú GET endpoint alebo starý transport SSE, tu zlyhajú. URL musí byť presne https://blckalpaca.at/mcp: s lomkou na konci server odpovie presmerovaním, ktoré nie každý klient nasleduje.
- Odpoveď 403 alebo kontrolná stránka namiesto JSON.
- Požiadavku zachytila ochrana proti botom od Cloudflare. Občas to postihne programy, ktoré volajú z dátových centier. Napíš na office@blckalpaca.at s časom a klientom, pozrieme sa do protokolov.
- Odpoveď 429.
- Na jednu IP adresu platí 240 požiadaviek za hodinu. Ako dlho čakať, uvádza hlavička Retry-After; stav kvóty uvádza RateLimit pri každej odpovedi. Kontrola webových stránok má vlastné limity: desať kontrol za hodinu pre tú istú stránku a 60 celkovo. Nad tento rámec nástroj odpovie s rate_limited.
- Nástroje chýbajú alebo ukazujú staré popisy.
- Mnohí asistenti si pri pripojení uložia zoznam nástrojov. Konektor odpoj a znova pripoj.
- Kontrola webových stránok odmietne adresu.
- Kontrolujú sa len verejné webové stránky cez http alebo https. Súkromné IP adresy, interné názvy hostiteľov, názvy bez domény a adresy, ktoré sa nedajú preložiť, nástroj odmietne s target_not_allowed.
- Stránka s ochranou proti botom dosiahne slabý výsledok v prístupe.
- Ak jej ochrana proti botom zablokuje našu kontrolu, spravidla blokuje aj AI agentov. Je to zistenie, nie chyba nástroja.
- Článok chýba v angličtine alebo slovenčine.
- Server nepreložený obsah vynechá, namiesto toho, aby ho poslal po nemecky. S locale „de“ nájdeš článok v pôvodnom jazyku.
Endpointy
Vygenerované z tej istej špecifikácie, ktorá sa poskytuje na /openapi.json. Táto tabuľka nemôže zostarnúť.
| Endpoint | operationId | Popis |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Prehľadať knowledge baseFulltextové vyhľadávanie v názve, definícii a hlavnom kľúčovom slove článkov knowledge base. |
| GET /api/health | getHealth | Stav aplikáciePre monitoring. |
| POST /api/contact | submitContactForm | Odoslať kontaktnú požiadavkuSpustí potvrdzovací e-mail s double opt-in. |
| POST /api/newsletter/subscribe | subscribeNewsletter | Prihlásiť sa na newsletterDouble opt-in. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Odhlásiť sa z newsletteraOčakáva token z odhlasovacieho odkazu v e-maile. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Overiť odhlasovací tokenOverí, či je odhlasovací token platný, bez toho aby odhlásenie vykonal. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Potvrdiť prihlásenie na newsletterCieľ odkazu z potvrdzovacieho e-mailu. |
| GET /api/contact/verify | verifyContactRequest | Potvrdiť kontaktnú požiadavkuCieľ odkazu z potvrdzovacieho e-mailu. |
| GET /api/chat | getChatSession | Načítať históriu chatovej relácie |
| POST /api/chat | sendChatMessage | Správa asistentovi na stránkeLimit požiadaviek na IP a navyše na reláciu. |
| GET /api/agentic-check | runAgenticCheck | Website auf Agent-Tauglichkeit pruefenPrueft eine oeffentlich erreichbare Website in fuenf gewichteten Bereichen: Zugang 30, Verstaendnis 25, Auffindbarkeit 20, EU-Transparenz & Datenschutz 15, Handlungsfaehigkeit 10. |
| POST /api/agentic-check | runAgenticCheckPost | Website auf Agent-Tauglichkeit pruefen (Formularweg)Identisch zu GET, nur mit den Angaben im Body. |
| GET /api/agentic-check/result/{token} | getAgenticCheckResult | Gespeicherten Befund abrufenLiefert einen bereits gelaufenen Befund erneut, ohne die geprueften Server noch einmal zu belasten. |
| POST /api/agentic-check/report | requestAgenticReport | Ausfuehrlichen Befund per E-Mail anfordern (browser-only)Verlangt einen Challenge-Token aus dem Formular. |
| POST /api/seo-audit | requestSeoAudit | Požiadať o bezplatný SEO audit (len v prehliadači)Vyžaduje challenge token, ktorý sa vytvorí v prehliadači pri načítaní formulára. |
Chybové odpovede
Každá chyba má rovnaký tvar: error nesie stabilný kód, message text pre človeka, hint hovorí, čo s tým. Kódy sa nikdy nepremenúvajú ani nepoužívajú na niečo iné. Dá sa na ne vetviť.
| Kód | Status | Poznámka |
|---|---|---|
| VALIDATION_ERROR | 400 | Skontroluj `fields` v tejto odpovedi — pri každom poli je uvedená konkrétna chyba. |
| INVALID_REQUEST | 400 | Väčšinou chýbajúci alebo expirovaný challenge token. Obnov stránku a odošli znova. |
| MISSING_FIELDS | 400 | Doplň polia uvedené v `fields` a odošli požiadavku znova. |
| MISSING_EMAIL | 400 | Pošli `email` v JSON tele požiadavky. |
| FIELD_TOO_LONG | 400 | Skráť pole uvedené v `fields`. |
| MALFORMED_BODY | 400 | Pošli platný JSON a nastav `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Očakáva sa adresa v tvare meno@domena.tld. |
| INVALID_EMAIL_DOMAIN | 400 | Doména nemá MX záznamy. Použi inú adresu. |
| DISPOSABLE_EMAIL | 400 | Použi trvalú adresu. S rovnakou adresou to neskúšaj znova. |
| ALREADY_SUBSCRIBED | 400 | Opakovanie nie je potrebné — stav je už taký, aký má byť. |
| INVALID_URL | 400 | Očakáva sa absolútna URL s http:// alebo https://. |
| INVALID_WEBSITE | 400 | Očakáva sa dostupná doména. |
| GDPR_REQUIRED | 400 | Nastav `gdprConsent` na true. Bez súhlasu sa nesmie nič ukladať. |
| INVALID_TOKEN | 400 | Tokeny platia jednorazovo. Vyžiadaj si nový. |
| TOKEN_EXPIRED | 410 | Vyžiadaj si nový token cez pôvodný endpoint. |
| METHOD_NOT_ALLOWED | 405 | Povolené metódy sú v hlavičke `Allow` tejto odpovede. |
| NOT_FOUND | 404 | Skontroluj cestu. Prehľad stránky je na /llms.txt. |
| UNAUTHORIZED | 401 | Tento endpoint je interný a očakáva platný secret. |
| RATE_LIMIT | 429 | Počkaj počet sekúnd uvedený v hlavičke `Retry-After`. `RateLimit` uvádza zostávajúci limit — táto hlavička je aj na úspešných odpovediach. |
| EMAIL_LIMIT | 429 | Limit platí na adresu, nie na IP. Zmena IP nepomôže. Tento limit zámerne nie je v hlavičke `RateLimit`. |
| SPAM_REJECTED | 400 | Neopakuj. Ak ide o omyl, napíš na office@blckalpaca.at. |
| UPSTREAM_UNAVAILABLE | 503 | Dočasné. Opakovanie s exponenciálnym odstupom má zmysel. |
| INTERNAL_ERROR | 500 | Nespôsobila to tvoja požiadavka. Skús neskôr. |
Príklady
Dve volania, ktoré fungujú bez prehliadača.
Prehľadať knowledge base
curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=sk"Zistiť stav
curl -i "https://blckalpaca.at/api/health"Niečo chýba alebo je zle
Ak endpoint odpovedá inak, než je tu popísané, chyba je v popise. Stačí krátka správa.
Kontakt