Przejdź do treści
01Dla programistów

Blck Alpaca API i zasoby dla programistów

Wszystko, co ta strona udostępnia w formie czytelnej maszynowo: specyfikacja OpenAPI, wersje treści w Markdown, llms.txt. Bez rejestracji, bez kluczy.

Czym to jest, a czym nie

Te endpointy obsługują formularze i wyszukiwarkę tej strony. Nie są produktowym API. Nie ma tu nic do integrowania, żadnego konta, żadnej gwarancji dostępności.

Mimo to są udokumentowane, z jednego powodu: kto czyta stronę automatycznie, nie powinien musieć odtwarzać endpointów z kodu frontendu. A kto natrafi na limit zapytań, powinien wcześniej wiedzieć, gdzie on leży.

Wewnętrznych endpointów celowo nie ma w specyfikacji: unieważniania cache, mapy przekierowań, pól ochrony przed spamem.

Zasoby

Stałe adresy URL. Nie zmieniają się.

URLPrzeznaczenie
/mcpSerwer MCP dla bazy wiedzy i sprawdzania stron internetowych. Streamable HTTP, rewizja 2026-07-28 oraz 2025-11-25 i starsze, tylko POST.
/openapi.jsonOpenAPI 3.1, JSON. Wszystkie publiczne endpointy ze schematami, operationId i kodami błędów.
/api/openapi.yamlTa sama specyfikacja w formacie YAML.
/llms.txtStruktura strony opisana prozą: usługi, baza wiedzy, badania, osobno dla każdego języka.
/llms-full.txtWersja rozszerzona ze streszczeniem treści zamiast samej listy linków.
/sitemap-index.xmlPełna lista adresów URL, podzielona na części.
/feed.xmlRSS wpisów na blogu.
/robots.txtReguły dla crawlerów, w tym sygnał Content-Signal (ai-train=no).

Uwierzytelnianie

Brak. Publiczne endpointy nie używają kluczy, tokenów ani kont.

Dwóch z nich i tak nie da się sensownie wywołać ze skryptu: formularz kontaktowy i audyt SEO wymagają tokenu, który generuje dopiero strona w przeglądarce. Specyfikacja oznacza je jako browser-only. Odpowiedź 200 nie oznacza tam też, że zapytanie zostało przetworzone. Zapytania rozpoznane jako zautomatyzowane dostają taką samą odpowiedź jak prawdziwe.

Limity

Endpointy z limitem zapytań pokazują jego stan w każdej odpowiedzi, nie dopiero przy 429. Jeśli czytasz nagłówki, nie musisz uderzać w ścianę, żeby poznać limit.

Wysyłane są równolegle dwa formaty: RateLimit i RateLimit-Policy według projektu IETF draft-ietf-httpapi-ratelimit-headers-11 oraz starsze nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset, które odczytuje większość bibliotek klienckich. Według stanu na sierpień 2026 projekt nie ma statusu RFC.

Jeśli obowiązuje więcej niż jeden limit, jak w czacie osobno na IP i na sesję, dwa pierwsze nagłówki wymieniają wszystkie. Starsze nagłówki podają tylko najbardziej restrykcyjny.

Nagłówki odpowiedzi przy wywołaniu czatu

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
Dozwolona liczba zapytań w oknie.
w
Długość okna w sekundach.
r
Ile z nich jeszcze zostało.
t
Sekundy do zresetowania. Różnica czasu, nie znacznik czasu.

Serwer MCP

Baza wiedzy i sprawdzanie stron internetowych są dostępne także jako serwer MCP pod POST /mcp. Asystent, który go podłączy, przeszukuje artykuły, pobiera pełne teksty bez parsowania HTML i sprawdza, czy publiczne strony internetowe są gotowe na agentów AI.

Transportem jest Streamable HTTP. Endpoint obsługuje dwie generacje protokołu pod tym samym adresem URL. Rewizja 2026-07-28 uczyniła rdzeń bezstanowym: bez handshake’u initialize, bez ID sesji, bez endpointu GET. Każde zapytanie to osobny POST, który niesie wersję protokołu w nagłówku MCP-Protocol-Version. Wymagane są też Mcp-Method oraz, przy tools/call, Mcp-Name; jeśli różnią się od treści żądania, zapytanie zostaje odrzucone.

Klienci korzystający z wersji 2025-11-25, 2025-06-18 lub 2025-03-26 zaczynają zamiast tego od initialize i pomijają nowe nagłówki. Oficjalne SDK w wersji 1.30.0 nadal korzysta z 2025-11-25, więc obecnie to typowa droga. Również tam nie powstaje sesja: serwer nie wydaje Mcp-Session-Id, a każdy POST jest niezależny. Wersja, której nie ma na żadnej z dwóch list, zostaje odrzucona z kodem -32022 i listą obsługiwanych rewizji.

Bez rejestracji. Obowiązuje ten sam limit co przy pozostałych endpointach, a treści można wykorzystywać z podaniem źródła.

NarzędzieOpis
search_knowledge_baseWyszukiwanie pełnotekstowe w tytule, krótkiej definicji i głównym słowie kluczowym artykułów bazy wiedzy Blck Alpaca (SEO, GEO, agenci AI, automatyzacja marketingu). Zwraca wyniki z URL i trzema segmentami ścieżki; pełny tekst pobiera get_knowledge_article.
list_knowledge_categoriesZwraca strukturę bazy wiedzy: wszystkie kategorie z ich tematami, każda pozycja ze slugiem i URL. Punkt wyjścia, gdy nie znasz frazy do wyszukania.
list_knowledge_topic_articlesWszystkie opublikowane artykuły jednego tematu. Slug kategorii i slug tematu muszą do siebie pasować i pochodzić z tego samego języka; jeśli nie pasują, odpowiedź wyjaśnia dlaczego.
get_knowledge_articlePełny tekst artykułu bazy wiedzy w Markdown, do tego krótka definicja, kluczowe wnioski, statystyki ze źródłami i FAQ. Segmenty ścieżki pochodzą z search_knowledge_base lub list_knowledge_topic_articles.
audit_websiteSprawdza, czy publiczna strona internetowa jest gotowa na agentów i GEO: czy agenci AI mogą do niej dotrzeć, przeczytać ją, zrozumieć i wykonywać na niej działania? Pobiera stronę tak jak agent (tylko GET, bez logowania, bez zmian) i ocenia pięć obszarów. Zwraca wynik ogólny, wyniki obszarów, trzy ustalenia o największym wpływie z odpowiednim poradnikiem, wszystkie pojedyncze testy i link do pełnego raportu. To nie jest ocena prawna.

Wyświetl listę narzędzi

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

Dostępny w Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base

Podłącz go do swojego asystenta AI

Jeden adres dla wszystkich: https://blckalpaca.at/mcp, bez rejestracji i bez klucza. Potem w asystencie masz do dyspozycji narzędzia bazy wiedzy i sprawdzanie stron internetowych (audit_website).

Ścieżki menu pochodzą z dokumentacji dostawców, stan na październik 2026. Jeśli dostawca zmieni interfejs, obowiązuje jego dokumentacja.

Claude (web i desktop)

  1. Otwórz Customize → Connectors, kliknij „+ Add”, a potem „Add custom connector”.
  2. Jako nazwę wpisz „Blck Alpaca”, a jako URL https://blckalpaca.at/mcp, dwa razy potwierdź przyciskiem „Continue” i zakończ przyciskiem „Add”. Uwierzytelnianie nie jest potrzebne.
  3. W czacie otwórz „+” → „Connectors” i włącz przełącznik przy Blck Alpaca.

Dostępne we wszystkich planach, w planie Free dozwolony jest jeden własny konektor. W planach Team i Enterprise najpierw dodaje go Owner w Organization settings → Connectors.

Claude Code

claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp
  1. Uruchom w terminalu. W sesji polecenie /mcp pokazuje, czy połączenie działa.

ChatGPT

  1. W ChatGPT Plugins kliknij „+”, a potem „Add custom MCP server”.
  2. Wpisz nazwę i opis, w sekcji „Connection” podaj URL https://blckalpaca.at/mcp, wybierz brak uwierzytelniania i zakończ przyciskiem „Create as a plugin”.
  3. W czacie wpisz „@” i wybierz Blck Alpaca.

Perplexity

  1. W ustawieniach konta otwórz „Connectors”, kliknij „+ Custom connector” i wybierz „Remote”.
  2. Wpisz nazwę i URL https://blckalpaca.at/mcp, jako uwierzytelnianie wybierz „None”.

Dla kont Pro, Max i Enterprise. W Enterprise administrator musi najpierw zezwolić na własne konektory.

Grok

  1. Otwórz grok.com/connectors, wybierz „New Connector”, a potem „Custom”.
  2. Wpisz URL https://blckalpaca.at/mcp. Grok sam rozpozna narzędzia i użyje ich, gdy pytanie będzie do nich pasować.

W Grok Business i Enterprise konektor najpierw dodaje administrator w konsoli xAI.

Antigravity (CLI, IDE i 2.0)

{
  "mcpServers": {
    "blckalpaca": {
      "serverUrl": "https://blckalpaca.at/mcp"
    }
  }
}
  1. Wklej wpis do ~/.gemini/config/mcp_config.json, a dla pojedynczego projektu do .agents/mcp_config.json. CLI, IDE i Antigravity 2.0 czytają ten sam format.
  2. Bez edycji pliku: w CLI polecenie /mcp otwiera menedżera MCP, w Antigravity 2.0 przejdź do Settings → Customizations → Installed MCP Servers → Add MCP.

Antigravity wymaga pola „serverUrl”. Pola „url” i „httpUrl” z Gemini CLI nie są obsługiwane. Od 18 czerwca 2026 Antigravity CLI (agy) zastępuje Gemini CLI w kontach bezpłatnych i subskrypcjach Google One, takich jak Google AI Pro.

Gemini CLI

gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp
  1. Uruchom w terminalu. Bez „-s user” wpis obowiązuje tylko dla bieżącego projektu. W sesji polecenie /mcp pokazuje status.

Już tylko dla kont Enterprise i przy korzystaniu z płatnego klucza API, wszyscy pozostali używają Antigravity. Jeśli edytujesz settings.json ręcznie: wpis w mcpServers potrzebuje „httpUrl”, a nie „url”. „url” jest przeznaczone dla starego transportu SSE.

Inni klienci

  1. Działa każdy klient obsługujący Streamable HTTP: typ serwera HTTP, adres https://blckalpaca.at/mcp, bez nagłówków. Klienci obsługujący tylko stary transport SSE nie są wspierani.

Rozwiązywanie problemów

Najczęstsze przeszkody przy podłączaniu, z przyczyną i rozwiązaniem.

Asystent zgłasza, że konfiguracja się nie powiodła.
Serwer obsługuje wyłącznie Streamable HTTP metodą POST, od rewizji MCP 2025-03-26. Klienci, którzy oczekują endpointu GET lub starego transportu SSE, tu zawodzą. URL musi brzmieć dokładnie https://blckalpaca.at/mcp: z ukośnikiem na końcu serwer odpowiada przekierowaniem, za którym nie każdy klient podąża.
Odpowiedź 403 lub strona weryfikacyjna zamiast JSON.
Zapytanie przechwyciła ochrona przed botami Cloudflare. Zdarza się to czasem programom, które łączą się z centrów danych. Napisz na office@blckalpaca.at, podając godzinę i klienta, a sprawdzimy logi.
Odpowiedź 429.
Na jeden adres IP przypada 240 zapytań na godzinę. Ile musisz czekać, podaje nagłówek Retry-After; stan limitu podaje RateLimit w każdej odpowiedzi. Sprawdzanie stron ma własne limity: dziesięć sprawdzeń na godzinę dla tej samej strony i 60 łącznie. Po ich przekroczeniu narzędzie odpowiada kodem rate_limited.
Brakuje narzędzi lub pokazują stare opisy.
Wielu asystentów zapisuje listę narzędzi przy podłączaniu. Odłącz konektor i podłącz go ponownie.
Sprawdzanie stron odrzuca adres.
Sprawdzane są tylko publiczne strony internetowe przez http lub https. Prywatne adresy IP, wewnętrzne nazwy hostów, nazwy bez końcówki domeny i adresy, których nie da się rozwiązać, narzędzie odrzuca z kodem target_not_allowed.
Strona z ochroną przed botami wypada słabo w obszarze dostępu.
Jeśli jej ochrona przed botami blokuje nasze sprawdzanie, zwykle blokuje też agentów AI. To wtedy wynik analizy, a nie błąd narzędzia.
Brakuje artykułu po polsku.
Serwer pomija nieprzetłumaczone treści, zamiast wysyłać je po niemiecku. Z locale „de” znajdziesz artykuł w języku oryginału.

Endpointy

Tabela wygenerowana z tej samej specyfikacji, którą serwer udostępnia pod /openapi.json. Nie może się zdezaktualizować.

EndpointoperationIdOpis
GET /api/knowledge-searchsearchKnowledgeBasePrzeszukaj bazę wiedzyWyszukiwanie pełnotekstowe w tytule, definicji i głównym słowie kluczowym artykułów bazy wiedzy.
GET /api/healthgetHealthStatus aplikacjiDo monitoringu.
POST /api/contactsubmitContactFormWyślij zapytanie kontaktoweWysyła e-mail potwierdzający w trybie double opt-in.
POST /api/newsletter/subscribesubscribeNewsletterZapisz się do newsletteraDouble opt-in.
POST /api/newsletter/unsubscribeunsubscribeNewsletterWypisz się z newsletteraOczekuje tokenu z linku wypisania w e-mailu.
GET /api/newsletter/unsubscribe/validatevalidateUnsubscribeTokenSprawdź token wypisaniaSprawdza, czy token wypisania jest ważny, bez wykonywania wypisania.
GET /api/newsletter/verifyverifyNewsletterSubscriptionPotwierdź zapis do newsletteraCel linku z e-maila potwierdzającego.
GET /api/contact/verifyverifyContactRequestPotwierdź zapytanie kontaktoweCel linku z e-maila potwierdzającego.
GET /api/chatgetChatSessionPobierz historię sesji czatu (tylko redakcja)Wymaga zalogowania do CMS.
POST /api/chatsendChatMessageWiadomość do asystenta na stronieLimit zapytań na IP i dodatkowo na sesję.
GET /api/agentic-checkrunAgenticCheckSprawdź, czy strona jest gotowa na agentówSprawdza publicznie dostępną stronę internetową w pięciu ważonych obszarach: dostęp 30, zrozumienie 25, odnajdywalność 20, przejrzystość UE i prywatność 15, zdolność do działania 10.
POST /api/agentic-checkrunAgenticCheckPostSprawdź, czy strona jest gotowa na agentów (przez formularz)Działa tak samo jak GET, tylko z danymi w treści żądania.
GET /api/agentic-check/result/{token}getAgenticCheckResultPobierz zapisany wynikZwraca ponownie wynik już przeprowadzonego sprawdzenia, bez ponownego obciążania sprawdzanych serwerów.
POST /api/agentic-check/reportrequestAgenticReportZamów szczegółowy raport e-mailem (tylko w przeglądarce)Wymaga challenge tokenu z formularza.
POST /api/seo-auditrequestSeoAuditZamów bezpłatny audyt SEO (tylko w przeglądarce)Wymaga challenge tokenu, który powstaje w przeglądarce przy ładowaniu formularza.

Odpowiedzi z błędem

Każdy błąd ma tę samą strukturę: error zawiera stabilny kod, message komunikat dla ludzi, hint mówi, co zrobić. Kody nigdy nie zmieniają nazwy ani nie są używane ponownie do czegoś innego. Możesz na nich opierać rozgałęzienia w kodzie.

KodStatusWskazówka
VALIDATION_ERROR400Sprawdź `fields` w tej odpowiedzi: przy każdym polu jest tam podany konkretny błąd.
INVALID_REQUEST400Zwykle brakujący lub wygasły challenge token. Odśwież stronę i wyślij ponownie.
MISSING_FIELDS400Uzupełnij pola wymienione w `fields` i wyślij zapytanie ponownie.
MISSING_EMAIL400Dołącz `email` do treści JSON.
FIELD_TOO_LONG400Skróć pole wymienione w `fields`.
MALFORMED_BODY400Wyślij poprawny JSON i ustaw `Content-Type: application/json`.
INVALID_EMAIL400Oczekiwany adres w formacie nazwa@domena.tld.
INVALID_EMAIL_DOMAIN400Domena nie ma rekordów MX. Użyj innego adresu.
DISPOSABLE_EMAIL400Użyj stałego adresu. Nie ponawiaj z tym samym adresem.
ALREADY_SUBSCRIBED400Ponowienie nie jest potrzebne: stan jest już zgodny z oczekiwanym.
INVALID_URL400Oczekiwany bezwzględny URL z http:// lub https://.
INVALID_WEBSITE400Oczekiwana osiągalna domena.
GDPR_REQUIRED400Ustaw `gdprConsent` na true. Bez zgody nie wolno niczego zapisywać.
INVALID_TOKEN400Tokeny są jednorazowe. Poproś o nowy.
TOKEN_EXPIRED410Poproś o nowy token przez pierwotny endpoint.
METHOD_NOT_ALLOWED405Dozwolone metody znajdziesz w nagłówku `Allow` tej odpowiedzi.
NOT_FOUND404Sprawdź ścieżkę. Przegląd strony znajdziesz pod /llms.txt.
UNAUTHORIZED401Ten endpoint jest wewnętrzny i oczekuje ważnego sekretu.
RATE_LIMIT429Odczekaj liczbę sekund podaną w nagłówku `Retry-After`. `RateLimit` podaje pozostały limit; ten nagłówek występuje też w udanych odpowiedziach.
EMAIL_LIMIT429Limit dotyczy adresu, nie IP. Zmiana IP nic nie da. Tego limitu celowo nie ma w nagłówku `RateLimit`.
SPAM_REJECTED400Nie ponawiaj. Jeśli to pomyłka, zgłoś to e-mailem na office@blckalpaca.at.
UPSTREAM_UNAVAILABLE503Chwilowe. Ponowienie z wykładniczym backoffem ma sens.
INTERNAL_ERROR500Nie spowodowało tego Twoje zapytanie. Spróbuj ponownie później.

Przykłady

Dwa wywołania, które działają bez przeglądarki.

Przeszukaj bazę wiedzy

curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=pl"

Sprawdź status

curl -i "https://blckalpaca.at/api/health"

Czegoś brakuje lub coś się nie zgadza

Jeśli endpoint odpowiada inaczej, niż opisano tutaj, błąd jest w opisie. Wystarczy krótka wiadomość.

Kontakt