Blck Alpaca API & Developer Resources
Everything this site offers in machine-readable form: OpenAPI specification, Markdown variants of the content, llms.txt. No sign-up, no keys.
What this is and what it is not
These endpoints serve the forms and the search of this website. They are not a product API. There is nothing to integrate with, no account, no availability guarantee.
They are documented anyway, for one reason: anyone reading the site programmatically should not have to reconstruct the endpoints from frontend code. And anyone running into a rate limit should know where it sits beforehand.
Internal endpoints are deliberately absent from the specification: cache invalidation, the redirect map, the spam filter fields.
Resources
Fixed URLs. They do not change.
| URL | Purpose |
|---|---|
| /mcp | MCP server for the knowledge base and the website check. Streamable HTTP, revision 2026-07-28 and 2025-11-25 downwards, POST only. |
| /openapi.json | OpenAPI 3.1, JSON. Every public endpoint with schemas, operationId and error codes. |
| /api/openapi.yaml | The same specification as YAML. |
| /llms.txt | Structure of the site in prose: services, knowledge base, studies, per language. |
| /llms-full.txt | Long form with substance rather than a bare link list. |
| /sitemap-index.xml | Complete URL list, chunked. |
| /feed.xml | RSS of the blog posts. |
| /robots.txt | Crawler rules including the content signal (ai-train=no). |
Authentication
None. The public endpoints have no keys, no tokens, no accounts.
Two of them still cannot be scripted sensibly: the contact form and the SEO audit require a token that only the page generates in the browser. The specification marks them browser-only. A 200 there also does not mean the request was processed. Requests detected as automated receive the same response as real ones.
Quotas
Rate-limited endpoints expose their state on every response, not just on the 429. Read the headers and you never have to hit the wall to learn the limit.
Two formats ship side by side: RateLimit and RateLimit-Policy per IETF draft-ietf-httpapi-ratelimit-headers-11, plus the legacy RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers most client libraries read. As of August 2026 the draft is not an RFC.
Where more than one quota applies, as with the chat counting per IP and per session, the first two headers name all of them. The legacy headers name only the tightest.
Response headers of a chat call
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
- Requests allowed within the window.
- w
- Window length in seconds.
- r
- Requests still available.
- t
- Seconds until reset. A delta, not a timestamp.
MCP server
The knowledge base and the website check are also reachable as an MCP server at POST /mcp. An assistant that connects it searches the articles, pulls full texts without parsing HTML, and checks public websites for AI-agent readiness.
Transport is Streamable HTTP. The endpoint serves two protocol generations on the same URL. Revision 2026-07-28 made the core stateless: no initialize handshake, no session id, no GET endpoint. Every request is a POST of its own and carries its protocol version in the MCP-Protocol-Version header. Mcp-Method is required, as is Mcp-Name on tools/call; requests whose headers disagree with the body are rejected.
Clients on 2025-11-25, 2025-06-18 or 2025-03-26 open with initialize instead and omit the new headers. The official SDK still sits at 2025-11-25 as of version 1.30.0, which makes that the common path today. No session is created there either: the server issues no Mcp-Session-Id, and every POST stands on its own. A version on neither list is rejected with -32022 and the list of supported revisions.
No sign-up. The same quota applies as to the other endpoints, and the content may be used with attribution.
| Tool | Description |
|---|---|
| search_knowledge_base | Full-text search across title, short definition and primary keyword of the Blck Alpaca knowledge base articles (SEO, GEO, AI agents, marketing automation). Returns matches with URL and path triple; get_knowledge_article fetches the full text. |
| list_knowledge_categories | Returns the structure of the knowledge base: every category with its topics, each with slug and URL. The entry point when no search term is known. |
| list_knowledge_topic_articles | All published articles of one topic. Category and topic slug must match and come from the same language; if they do not, the response says why. |
| get_knowledge_article | Full text of a knowledge base article as Markdown, plus short definition, key takeaways, sourced statistics and FAQ. The path triple comes from search_knowledge_base or list_knowledge_topic_articles. |
| audit_website | Checks a public website for AI-agent readiness and GEO: can AI agents reach, read, understand and act on it? Fetches the site the way an agent does (GET only, no login, no changes) and scores five areas. Returns the overall score, area scores, the three findings with the most impact and a matching guide, every single check and a link to the full report. Not a legal assessment. |
List the tools
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"}'Listed in Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base
Connect it to your AI assistant
One address for all of them: https://blckalpaca.at/mcp, no sign-up and no key. Your assistant then has the knowledge base tools and the website check (audit_website).
The menu paths come from each provider’s documentation as of October 2026. If a provider changes its interface, its documentation wins.
Claude (web and desktop)
- Open Customize → Connectors, click “+ Add”, then “Add custom connector”.
- Enter “Blck Alpaca” as the name and https://blckalpaca.at/mcp as the URL, confirm twice with “Continue” and finish with “Add”. No authentication is needed.
- In a chat, open “+” → “Connectors” and switch on Blck Alpaca.
Available on every plan; the Free plan allows one custom connector. On Team and Enterprise an Owner adds it first under Organization settings → Connectors.
Claude Code
claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp- Run this in your terminal. Inside a session, /mcp shows whether the connection is up.
ChatGPT
- In ChatGPT Plugins, click “+”, then “Add custom MCP server”.
- Enter a name and description, give https://blckalpaca.at/mcp as the URL under “Connection”, choose no authentication and finish with “Create as a plugin”.
- In a chat, type “@” and pick Blck Alpaca.
Perplexity
- In your account settings, open “Connectors”, click “+ Custom connector” and choose “Remote”.
- Enter a name and https://blckalpaca.at/mcp as the URL, with authentication “None”.
For Pro, Max and Enterprise accounts. On Enterprise an admin has to allow custom connectors first.
Grok
- Open grok.com/connectors, choose “New Connector”, then “Custom”.
- Enter https://blckalpaca.at/mcp as the URL. Grok discovers the tools itself and uses them when a question fits.
On Grok Business and Enterprise an admin first adds the connector in the xAI console.
Gemini CLI
gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp- Run this in your terminal. Without “-s user” the entry applies only to the current project. Inside a session, /mcp shows the status.
If you edit settings.json yourself: the entry under mcpServers needs “httpUrl”, not “url”. “url” is meant for the old SSE transport.
Other clients
- Any client that speaks Streamable HTTP works: server type HTTP, address https://blckalpaca.at/mcp, no headers. Clients limited to the old SSE transport are not supported.
Troubleshooting
The most common stumbling blocks when connecting, with cause and fix.
- The assistant says the setup failed.
- The server speaks Streamable HTTP over POST only, from MCP revision 2025-03-26 onwards. Clients that expect a GET endpoint or the old SSE transport fail here. The URL must be exactly https://blckalpaca.at/mcp: with a trailing slash the server answers with a redirect that not every client follows.
- A 403 response or a challenge page instead of JSON.
- Cloudflare’s bot protection intercepted the request. This occasionally hits programs calling from data centres. Write to office@blckalpaca.at with the time and the client, and we will check the logs.
- A 429 response.
- Each IP address gets 240 requests per hour. The Retry-After header says how long to wait; RateLimit states the remaining quota on every response. The website check has its own limits: ten checks per hour for the same website and 60 in total. Beyond that the tool answers with rate_limited.
- Tools are missing or show old descriptions.
- Many assistants store the tool list when you connect. Disconnect the connector and connect it again.
- The website check rejects an address.
- Only public websites over http or https are checked. Private IP addresses, internal hostnames, names without a domain ending and addresses that do not resolve are rejected with target_not_allowed.
- A website with bot protection scores poorly on access.
- If its bot protection blocks our check, it usually blocks AI agents too. That is a finding, not a fault of the tool.
- An article is missing in English or Slovak.
- The server leaves out untranslated content rather than serving it in German. With locale “de” you find the article in its original language.
Endpoints
Generated from the same specification served at /openapi.json. This table cannot go stale.
| Endpoint | operationId | Description |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Search the knowledge baseFull-text search across title, definition and primary keyword of the knowledge base articles. |
| GET /api/health | getHealth | Application statusFor monitoring. |
| POST /api/contact | submitContactForm | Send a contact requestTriggers a double opt-in confirmation email. |
| POST /api/newsletter/subscribe | subscribeNewsletter | Subscribe to the newsletterDouble opt-in. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Unsubscribe from the newsletterExpects the token from the unsubscribe link in the email. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Check an unsubscribe tokenChecks whether an unsubscribe token is valid without performing the unsubscribe. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Confirm a newsletter subscriptionTarget of the link in the confirmation email. |
| GET /api/contact/verify | verifyContactRequest | Confirm a contact requestTarget of the link in the confirmation email. |
| GET /api/chat | getChatSession | Retrieve the history of a chat session |
| POST /api/chat | sendChatMessage | Message to the website assistantRate limited per IP and additionally per 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 | Request a free SEO audit (browser only)Requires a challenge token generated in the browser when the form loads. |
Error responses
Every error has the same shape: error carries a stable code, message the human-readable text, hint says what to do about it. Codes are never renamed and never reused for something else. You can branch on them.
| Code | Status | Hint |
|---|---|---|
| VALIDATION_ERROR | 400 | Check `fields` in this response — it names the concrete error per field. |
| INVALID_REQUEST | 400 | Usually a missing or expired challenge token. Reload the page and submit again. |
| MISSING_FIELDS | 400 | Add the fields listed in `fields` and send the request again. |
| MISSING_EMAIL | 400 | Include `email` in the JSON body. |
| FIELD_TOO_LONG | 400 | Shorten the field named in `fields`. |
| MALFORMED_BODY | 400 | Send valid JSON and set `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Expected an address of the form name@domain.tld. |
| INVALID_EMAIL_DOMAIN | 400 | The domain has no MX records. Use a different address. |
| DISPOSABLE_EMAIL | 400 | Use a permanent address. Do not retry with the same one. |
| ALREADY_SUBSCRIBED | 400 | No retry needed — the state is already the one you wanted. |
| INVALID_URL | 400 | Expected an absolute URL with http:// or https://. |
| INVALID_WEBSITE | 400 | Expected a reachable domain. |
| GDPR_REQUIRED | 400 | Set `gdprConsent` to true. Without consent nothing may be stored. |
| INVALID_TOKEN | 400 | Tokens are single-use. Request a new one. |
| TOKEN_EXPIRED | 410 | Request a new token through the original endpoint. |
| METHOD_NOT_ALLOWED | 405 | The permitted methods are in the `Allow` header of this response. |
| NOT_FOUND | 404 | Check the path. An overview of the site is at /llms.txt. |
| UNAUTHORIZED | 401 | This endpoint is internal and expects a valid secret. |
| RATE_LIMIT | 429 | Wait the number of seconds given in the `Retry-After` header. `RateLimit` states the remaining quota — that header is present on successful responses too. |
| EMAIL_LIMIT | 429 | The limit applies per address, not per IP. Changing IP does not help. This limit is deliberately absent from the `RateLimit` header. |
| SPAM_REJECTED | 400 | Do not retry. If misjudged, report it by email to office@blckalpaca.at. |
| UPSTREAM_UNAVAILABLE | 503 | Temporary. Retrying with exponential backoff makes sense. |
| INTERNAL_ERROR | 500 | Not caused by your request. Try again later. |
Examples
Two calls that work without a browser.
Search the knowledge base
curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=en"Query the status
curl -i "https://blckalpaca.at/api/health"Something missing or wrong
If an endpoint behaves differently from what is described here, the description is the bug. A short message is enough.
Contact