Blck Alpaca API & Entwickler-Ressourcen
Alles, was diese Website maschinenlesbar anbietet: OpenAPI-Spezifikation, Markdown-Varianten der Inhalte, llms.txt. Keine Anmeldung, keine Schlüssel.
Was das ist und was nicht
Die Endpunkte hier bedienen die Formulare und die Suche dieser Website. Sie sind keine Produkt-API. Es gibt nichts zu integrieren, kein Konto, keine Zusicherung zur Verfügbarkeit.
Dokumentiert sind sie trotzdem, aus einem Grund: Wer die Seite automatisiert liest, soll die Endpunkte nicht aus dem Frontend-Code rekonstruieren müssen. Und wer gegen ein Rate-Limit läuft, soll vorher wissen, wo es liegt.
Interne Endpunkte stehen bewusst nicht in der Spezifikation: Cache-Invalidierung, Redirect-Karte, die Felder des Spam-Schutzes.
Ressourcen
Feste URLs. Sie ändern sich nicht.
| URL | Zweck |
|---|---|
| /mcp | MCP-Server für Knowledge Base und Website-Check. Streamable HTTP, Revision 2026-07-28 und 2025-11-25 abwärts, nur POST. |
| /openapi.json | OpenAPI 3.1, JSON. Alle öffentlichen Endpunkte mit Schemas, operationId und Fehlercodes. |
| /api/openapi.yaml | Dieselbe Spezifikation als YAML. |
| /llms.txt | Struktur der Website in Prosa: Services, Knowledge Base, Studien, pro Sprache. |
| /llms-full.txt | Langfassung mit inhaltlichem Abriss statt reiner Linkliste. |
| /sitemap-index.xml | Vollständige URL-Liste, gechunkt. |
| /feed.xml | RSS der Blog-Beiträge. |
| /robots.txt | Crawler-Regeln inklusive Content-Signal (ai-train=no). |
Authentifizierung
Keine. Die öffentlichen Endpunkte kennen weder Schlüssel noch Token noch Konten.
Zwei lassen sich trotzdem nicht sinnvoll skripten: Kontaktformular und SEO-Audit verlangen einen Token, den erst die Seite im Browser erzeugt. In der Spezifikation sind sie als browser-only markiert. Ein 200er bedeutet dort außerdem nicht, dass die Anfrage bearbeitet wurde. Als automatisiert erkannte Anfragen bekommen dieselbe Antwort wie echte.
Kontingente
Endpunkte mit Rate-Limit legen ihren Stand offen, und zwar auf jeder Antwort, nicht erst auf dem 429er. Wer die Header liest, muss nicht gegen die Wand laufen, um das Limit zu kennen.
Ausgeliefert werden zwei Formate nebeneinander: RateLimit und RateLimit-Policy nach dem IETF-Entwurf draft-ietf-httpapi-ratelimit-headers-11, dazu die Legacy-Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, die die meisten Client-Bibliotheken lesen. Der Entwurf ist mit Stand August 2026 kein RFC.
Gilt mehr als ein Kontingent, beim Chat etwa pro IP und pro Session, nennen die beiden erstgenannten Header alle davon. Die Legacy-Header nennen nur das knappste.
Antwort-Header eines Chat-Aufrufs
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
- Erlaubte Anfragen im Fenster.
- w
- Länge des Fensters in Sekunden.
- r
- Davon noch frei.
- t
- Sekunden bis zum Zurücksetzen. Ein Delta, kein Zeitstempel.
MCP-Server
Die Knowledge Base und der Website-Check sind zusätzlich als MCP-Server erreichbar, unter POST /mcp. Ein Assistent, der ihn verbindet, durchsucht die Artikel, holt Volltexte, ohne HTML zu parsen, und prüft öffentliche Websites auf Agent-Tauglichkeit.
Transport ist Streamable HTTP. Der Endpunkt bedient zwei Protokoll-Generationen auf derselben URL. Revision 2026-07-28 hat den Kern zustandslos gemacht: kein initialize-Handshake, keine Sitzungs-ID, kein GET-Endpunkt. Jede Anfrage ist ein POST für sich und trägt ihre Protokoll-Version im Header MCP-Protocol-Version. Dazu sind Mcp-Method und, bei tools/call, Mcp-Name vorgeschrieben; weichen sie vom Body ab, wird die Anfrage abgelehnt.
Clients auf 2025-11-25, 2025-06-18 oder 2025-03-26 beginnen stattdessen mit initialize und lassen die neuen Header weg. Das offizielle SDK steht in Version 1.30.0 noch auf 2025-11-25, insofern ist das derzeit der übliche Weg. Eine Sitzung entsteht auch dort nicht: Der Server gibt keine Mcp-Session-Id aus, jeder POST steht für sich. Eine Version, die auf keiner der beiden Listen steht, wird mit -32022 und der Liste der unterstützten Revisionen abgelehnt.
Keine Anmeldung. Es gilt dasselbe Kontingent wie bei den übrigen Endpunkten, und die Inhalte dürfen mit Quellennennung verwendet werden.
| Werkzeug | Beschreibung |
|---|---|
| search_knowledge_base | Volltextsuche über Titel, Kurzdefinition und Hauptkeyword der Knowledge-Base-Artikel von Blck Alpaca (SEO, GEO, KI-Agenten, Marketing-Automatisierung). Liefert Treffer mit URL und Pfad-Tripel; den Volltext holt get_knowledge_article. |
| list_knowledge_categories | Gibt den Aufbau der Knowledge Base zurück: alle Kategorien mit ihren Themen, jeweils mit Slug und URL. Einstiegspunkt, wenn kein Suchbegriff bekannt ist. |
| list_knowledge_topic_articles | Alle veröffentlichten Artikel eines Themas. Kategorie- und Themen-Slug müssen zusammenpassen und stammen aus derselben Sprache; passen sie nicht, sagt die Antwort warum. |
| get_knowledge_article | Volltext eines Knowledge-Base-Artikels als Markdown, dazu Kurzdefinition, Kernaussagen, belegte Statistiken mit Quelle und FAQ. Das Pfad-Tripel stammt aus search_knowledge_base oder list_knowledge_topic_articles. |
| audit_website | Prüft eine öffentliche Website auf Agent-Tauglichkeit und GEO: Können KI-Agents sie erreichen, lesen, verstehen und mit ihr arbeiten? Ruft die Seite so ab wie ein Agent (nur GET, ohne Anmeldung, ohne Änderungen) und bewertet fünf Bereiche. Liefert Gesamtwert, Bereichswerte, die drei wirksamsten Befunde mit passendem Guide, alle Einzelprüfungen und einen Link zum vollständigen Bericht. Keine Rechtsbewertung. |
Werkzeuge auflisten
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"}'Gelistet in Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base
In deinem KI-Assistenten verbinden
Eine Adresse für alle: https://blckalpaca.at/mcp, ohne Anmeldung und ohne Schlüssel. Danach stehen im Assistenten die Werkzeuge der Knowledge Base und der Website-Check (audit_website) bereit.
Die Menüpfade stammen aus der Dokumentation der Anbieter, Stand Oktober 2026. Ändert ein Anbieter seine Oberfläche, gilt seine Dokumentation.
Claude (Web und Desktop)
- Customize → Connectors öffnen, auf „+ Add" und dann auf „Add custom connector" klicken.
- Als Name „Blck Alpaca" und als URL https://blckalpaca.at/mcp eintragen, zweimal mit „Continue" bestätigen und mit „Add" abschließen. Eine Authentifizierung braucht es nicht.
- Im Chat über „+" → „Connectors" den Schalter für Blck Alpaca einschalten.
In allen Plänen verfügbar, im Free-Plan ist ein eigener Connector erlaubt. In Team und Enterprise richtet ihn zuerst ein Owner unter Organization settings → Connectors ein.
Claude Code
claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp- Im Terminal ausführen. In einer Sitzung zeigt /mcp, ob die Verbindung steht.
ChatGPT
- Unter ChatGPT Plugins auf „+" und dann auf „Add custom MCP server" klicken.
- Name und Beschreibung eintragen, unter „Connection" die URL https://blckalpaca.at/mcp angeben, keine Authentifizierung wählen und mit „Create as a plugin" abschließen.
- Im Chat „@" tippen und Blck Alpaca auswählen.
Perplexity
- In den Kontoeinstellungen unter „Connectors" auf „+ Custom connector" klicken und „Remote" wählen.
- Name und URL https://blckalpaca.at/mcp eintragen, als Authentifizierung „None".
Für Pro-, Max- und Enterprise-Konten. In Enterprise muss ein Admin eigene Connectors erst freigeben.
Grok
- grok.com/connectors öffnen, „New Connector" und dann „Custom" wählen.
- Die URL https://blckalpaca.at/mcp eintragen. Grok erkennt die Werkzeuge selbst und nutzt sie, wenn eine Frage dazu passt.
In Grok Business und Enterprise richtet ein Admin den Connector zuerst in der xAI-Konsole ein.
Gemini CLI
gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp- Im Terminal ausführen. Ohne „-s user" gilt der Eintrag nur für das aktuelle Projekt. In einer Sitzung zeigt /mcp den Status.
Wer settings.json selbst pflegt: Der Eintrag unter mcpServers braucht „httpUrl", nicht „url". „url" ist für den alten SSE-Transport gedacht.
Andere Clients
- Jeder Client mit Streamable HTTP funktioniert: Server-Typ HTTP, Adresse https://blckalpaca.at/mcp, keine Header. Clients, die nur den alten SSE-Transport beherrschen, werden nicht unterstützt.
Fehlerbehebung
Die häufigsten Stolpersteine beim Verbinden, mit Ursache und Abhilfe.
- Der Assistent meldet, die Einrichtung sei fehlgeschlagen.
- Der Server spricht nur Streamable HTTP mit POST, ab MCP-Revision 2025-03-26. Clients, die einen GET-Endpunkt oder den alten SSE-Transport erwarten, scheitern hier. Die URL muss genau https://blckalpaca.at/mcp lauten: Mit Schrägstrich am Ende antwortet der Server mit einer Weiterleitung, der nicht jeder Client folgt.
- Antwort 403 oder eine Prüfseite statt JSON.
- Dann hat der Bot-Schutz von Cloudflare die Anfrage abgefangen. Das trifft vereinzelt Programme, die aus Rechenzentren anrufen. Schreib an office@blckalpaca.at, mit Uhrzeit und Client, dann sehen wir in den Protokollen nach.
- Antwort 429.
- Pro IP-Adresse gelten 240 Anfragen pro Stunde. Wie lange du warten musst, steht im Header Retry-After; den Stand des Kontingents nennt RateLimit auf jeder Antwort. Der Website-Check hat eigene Grenzen: zehn Prüfungen pro Stunde für dieselbe Website und 60 insgesamt. Darüber antwortet das Werkzeug mit rate_limited.
- Werkzeuge fehlen oder zeigen alte Beschreibungen.
- Viele Assistenten speichern die Werkzeugliste beim Verbinden. Connector trennen und neu verbinden.
- Der Website-Check lehnt eine Adresse ab.
- Geprüft werden nur öffentliche Websites über http oder https. Private IP-Adressen, interne Hostnamen, Namen ohne Domain-Endung und Adressen, die sich nicht auflösen lassen, lehnt das Werkzeug mit target_not_allowed ab.
- Eine Website mit Bot-Schutz schneidet beim Zugang schlecht ab.
- Blockiert ihr Bot-Schutz unseren Check, blockiert er in der Regel auch KI-Agents. Das ist dann ein Befund, kein Fehler des Werkzeugs.
- Ein Artikel fehlt auf Englisch oder Slowakisch.
- Nicht übersetzte Inhalte lässt der Server weg, statt sie auf Deutsch auszuliefern. Mit locale „de" findest du den Artikel in der Originalsprache.
Endpunkte
Erzeugt aus derselben Spezifikation, die unter /openapi.json ausgeliefert wird. Diese Tabelle kann nicht veralten.
| Endpunkt | operationId | Beschreibung |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Knowledge-Base durchsuchenVolltextsuche über Titel, Definition und Hauptkeyword der Knowledge-Base-Artikel. |
| GET /api/health | getHealth | Status der AnwendungFür Monitoring. |
| POST /api/contact | submitContactForm | Kontaktanfrage sendenLöst eine Double-Opt-In-Bestätigungsmail aus. |
| POST /api/newsletter/subscribe | subscribeNewsletter | Newsletter abonnierenDouble-Opt-In. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Newsletter abbestellenErwartet den Token aus dem Abmeldelink der E-Mail. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Abmelde-Token prüfenPrüft, ob ein Abmelde-Token gültig ist, ohne die Abmeldung auszuführen. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Newsletter-Anmeldung bestätigenZiel des Links aus der Bestätigungsmail. |
| GET /api/contact/verify | verifyContactRequest | Kontaktanfrage bestätigenZiel des Links aus der Bestätigungsmail. |
| GET /api/chat | getChatSession | Verlauf einer Chat-Session abrufen (nur Redaktion)Verlangt eine Anmeldung am CMS. |
| POST /api/chat | sendChatMessage | Nachricht an den Website-AssistentenRate-Limit pro IP und zusätzlich pro Session. |
| 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 | Kostenlosen SEO-Audit anfordern (browser-only)Verlangt einen Challenge-Token, der beim Laden des Formulars im Browser erzeugt wird. |
Fehlerantworten
Jeder Fehler hat dieselbe Form: error trägt einen stabilen Code, message die Meldung für Menschen, hint sagt, was zu tun ist. Die Codes werden nie umbenannt und nie für etwas anderes wiederverwendet. Auf sie lässt sich verzweigen.
| Code | Status | Hinweis |
|---|---|---|
| VALIDATION_ERROR | 400 | Prüfe `fields` in dieser Antwort - dort steht pro Feld der konkrete Fehler. |
| INVALID_REQUEST | 400 | Meist ein fehlendes oder abgelaufenes Challenge-Token. Seite neu laden und erneut senden. |
| MISSING_FIELDS | 400 | Ergänze die in `fields` genannten Felder und sende die Anfrage erneut. |
| MISSING_EMAIL | 400 | Sende `email` im JSON-Body mit. |
| FIELD_TOO_LONG | 400 | Kürze das in `fields` genannte Feld. |
| MALFORMED_BODY | 400 | Sende gültiges JSON und setze `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Erwartet wird eine Adresse der Form name@domain.tld. |
| INVALID_EMAIL_DOMAIN | 400 | Die Domain hat keine MX-Records. Verwende eine andere Adresse. |
| DISPOSABLE_EMAIL | 400 | Verwende eine dauerhafte Adresse. Kein Retry mit derselben Adresse. |
| ALREADY_SUBSCRIBED | 400 | Kein Retry nötig - der Zustand ist bereits der gewünschte. |
| INVALID_URL | 400 | Erwartet wird eine absolute URL mit http:// oder https://. |
| INVALID_WEBSITE | 400 | Erwartet wird eine erreichbare Domain. |
| GDPR_REQUIRED | 400 | Setze `gdprConsent` auf true. Ohne Einwilligung darf nicht gespeichert werden. |
| INVALID_TOKEN | 400 | Token gelten einmalig. Fordere einen neuen an. |
| TOKEN_EXPIRED | 410 | Fordere über den ursprünglichen Endpunkt einen neuen Token an. |
| METHOD_NOT_ALLOWED | 405 | Die erlaubten Methoden stehen im `Allow`-Header dieser Antwort. |
| NOT_FOUND | 404 | Prüfe den Pfad. Eine Übersicht der Site steht unter /llms.txt. |
| UNAUTHORIZED | 401 | Dieser Endpunkt ist intern und erwartet ein gültiges Secret. |
| RATE_LIMIT | 429 | Warte die im `Retry-After`-Header genannte Anzahl Sekunden ab. `RateLimit` nennt das verbleibende Kontingent - der Header steht auch auf erfolgreichen Antworten. |
| EMAIL_LIMIT | 429 | Das Limit gilt pro Adresse, nicht pro IP. Ein IP-Wechsel hilft nicht. Dieses Limit steht bewusst nicht im `RateLimit`-Header. |
| SPAM_REJECTED | 400 | Kein Retry. Bei Fehleinschätzung per E-Mail an office@blckalpaca.at melden. |
| UPSTREAM_UNAVAILABLE | 503 | Vorübergehend. Wiederholung mit exponentiellem Backoff ist sinnvoll. |
| INTERNAL_ERROR | 500 | Nicht durch die Anfrage verursacht. Später erneut versuchen. |
Beispiele
Zwei Aufrufe, die ohne Browser funktionieren.
Knowledge Base durchsuchen
curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=de"Status abfragen
curl -i "https://blckalpaca.at/api/health"Etwas fehlt oder ist falsch
Wenn ein Endpunkt anders antwortet als hier beschrieben, ist die Beschreibung der Fehler. Eine kurze Nachricht genügt.
Kontakt