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. Streamable HTTP, revízia 2026-07-28, 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 je dostupná aj ako MCP server na POST /mcp. Asistent, ktorý ho pripojí, prehľadáva články a načíta plné texty bez parsovania HTML.
Transport je Streamable HTTP podľa revízie 2026-07-28. Tá 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.
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. |
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"}'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. |
| 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 [email protected]. |
| 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 [email protected]. |
| 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