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 die Knowledge Base. Streamable HTTP, Revision 2026-07-28, 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 ist zusätzlich als MCP-Server erreichbar, unter POST /mcp. Ein Assistent, der ihn verbindet, durchsucht die Artikel und holt Volltexte, ohne HTML zu parsen.
Transport ist Streamable HTTP nach Revision 2026-07-28. Diese Revision 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.
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. |
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"}'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 |
| POST /api/chat | sendChatMessage | Nachricht an den Website-AssistentenRate-Limit pro IP und zusätzlich pro Session. |
| 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 [email protected]. |
| 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 [email protected] 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