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ę.
| URL | Przeznaczenie |
|---|---|
| /mcp | Serwer MCP dla bazy wiedzy i sprawdzania stron internetowych. Streamable HTTP, rewizja 2026-07-28 oraz 2025-11-25 i starsze, tylko POST. |
| /openapi.json | OpenAPI 3.1, JSON. Wszystkie publiczne endpointy ze schematami, operationId i kodami błędów. |
| /api/openapi.yaml | Ta sama specyfikacja w formacie YAML. |
| /llms.txt | Struktura strony opisana prozą: usługi, baza wiedzy, badania, osobno dla każdego języka. |
| /llms-full.txt | Wersja rozszerzona ze streszczeniem treści zamiast samej listy linków. |
| /sitemap-index.xml | Pełna lista adresów URL, podzielona na części. |
| /feed.xml | RSS wpisów na blogu. |
| /robots.txt | Reguł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ędzie | Opis |
|---|---|
| search_knowledge_base | Wyszukiwanie 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_categories | Zwraca 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_articles | Wszystkie 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_article | Peł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_website | Sprawdza, 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)
- Otwórz Customize → Connectors, kliknij „+ Add”, a potem „Add custom connector”.
- 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.
- 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- Uruchom w terminalu. W sesji polecenie /mcp pokazuje, czy połączenie działa.
ChatGPT
- W ChatGPT Plugins kliknij „+”, a potem „Add custom MCP server”.
- Wpisz nazwę i opis, w sekcji „Connection” podaj URL https://blckalpaca.at/mcp, wybierz brak uwierzytelniania i zakończ przyciskiem „Create as a plugin”.
- W czacie wpisz „@” i wybierz Blck Alpaca.
Perplexity
- W ustawieniach konta otwórz „Connectors”, kliknij „+ Custom connector” i wybierz „Remote”.
- 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
- Otwórz grok.com/connectors, wybierz „New Connector”, a potem „Custom”.
- 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"
}
}
}- 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.
- 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- 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
- 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ć.
| Endpoint | operationId | Opis |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Przeszukaj bazę wiedzyWyszukiwanie pełnotekstowe w tytule, definicji i głównym słowie kluczowym artykułów bazy wiedzy. |
| GET /api/health | getHealth | Status aplikacjiDo monitoringu. |
| POST /api/contact | submitContactForm | Wyślij zapytanie kontaktoweWysyła e-mail potwierdzający w trybie double opt-in. |
| POST /api/newsletter/subscribe | subscribeNewsletter | Zapisz się do newsletteraDouble opt-in. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Wypisz się z newsletteraOczekuje tokenu z linku wypisania w e-mailu. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Sprawdź token wypisaniaSprawdza, czy token wypisania jest ważny, bez wykonywania wypisania. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Potwierdź zapis do newsletteraCel linku z e-maila potwierdzającego. |
| GET /api/contact/verify | verifyContactRequest | Potwierdź zapytanie kontaktoweCel linku z e-maila potwierdzającego. |
| GET /api/chat | getChatSession | Pobierz historię sesji czatu (tylko redakcja)Wymaga zalogowania do CMS. |
| POST /api/chat | sendChatMessage | Wiadomość do asystenta na stronieLimit zapytań na IP i dodatkowo na sesję. |
| GET /api/agentic-check | runAgenticCheck | Sprawdź, 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-check | runAgenticCheckPost | Sprawdź, 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} | getAgenticCheckResult | Pobierz zapisany wynikZwraca ponownie wynik już przeprowadzonego sprawdzenia, bez ponownego obciążania sprawdzanych serwerów. |
| POST /api/agentic-check/report | requestAgenticReport | Zamów szczegółowy raport e-mailem (tylko w przeglądarce)Wymaga challenge tokenu z formularza. |
| POST /api/seo-audit | requestSeoAudit | Zamó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.
| Kod | Status | Wskazówka |
|---|---|---|
| VALIDATION_ERROR | 400 | Sprawdź `fields` w tej odpowiedzi: przy każdym polu jest tam podany konkretny błąd. |
| INVALID_REQUEST | 400 | Zwykle brakujący lub wygasły challenge token. Odśwież stronę i wyślij ponownie. |
| MISSING_FIELDS | 400 | Uzupełnij pola wymienione w `fields` i wyślij zapytanie ponownie. |
| MISSING_EMAIL | 400 | Dołącz `email` do treści JSON. |
| FIELD_TOO_LONG | 400 | Skróć pole wymienione w `fields`. |
| MALFORMED_BODY | 400 | Wyślij poprawny JSON i ustaw `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Oczekiwany adres w formacie nazwa@domena.tld. |
| INVALID_EMAIL_DOMAIN | 400 | Domena nie ma rekordów MX. Użyj innego adresu. |
| DISPOSABLE_EMAIL | 400 | Użyj stałego adresu. Nie ponawiaj z tym samym adresem. |
| ALREADY_SUBSCRIBED | 400 | Ponowienie nie jest potrzebne: stan jest już zgodny z oczekiwanym. |
| INVALID_URL | 400 | Oczekiwany bezwzględny URL z http:// lub https://. |
| INVALID_WEBSITE | 400 | Oczekiwana osiągalna domena. |
| GDPR_REQUIRED | 400 | Ustaw `gdprConsent` na true. Bez zgody nie wolno niczego zapisywać. |
| INVALID_TOKEN | 400 | Tokeny są jednorazowe. Poproś o nowy. |
| TOKEN_EXPIRED | 410 | Poproś o nowy token przez pierwotny endpoint. |
| METHOD_NOT_ALLOWED | 405 | Dozwolone metody znajdziesz w nagłówku `Allow` tej odpowiedzi. |
| NOT_FOUND | 404 | Sprawdź ścieżkę. Przegląd strony znajdziesz pod /llms.txt. |
| UNAUTHORIZED | 401 | Ten endpoint jest wewnętrzny i oczekuje ważnego sekretu. |
| RATE_LIMIT | 429 | Odczekaj liczbę sekund podaną w nagłówku `Retry-After`. `RateLimit` podaje pozostały limit; ten nagłówek występuje też w udanych odpowiedziach. |
| EMAIL_LIMIT | 429 | Limit dotyczy adresu, nie IP. Zmiana IP nic nie da. Tego limitu celowo nie ma w nagłówku `RateLimit`. |
| SPAM_REJECTED | 400 | Nie ponawiaj. Jeśli to pomyłka, zgłoś to e-mailem na office@blckalpaca.at. |
| UPSTREAM_UNAVAILABLE | 503 | Chwilowe. Ponowienie z wykładniczym backoffem ma sens. |
| INTERNAL_ERROR | 500 | Nie 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