Blck Alpaca API et ressources pour développeurs
Tout ce que ce site propose sous forme lisible par machine : spécification OpenAPI, versions Markdown des contenus, llms.txt. Sans inscription, sans clé.
Ce que c’est, et ce que ce n’est pas
Ces endpoints servent les formulaires et la recherche de ce site. Ce n’est pas une API produit. Il n’y a rien à intégrer, pas de compte, aucune garantie de disponibilité.
Ils sont tout de même documentés, pour une raison : qui lit le site de façon automatisée ne devrait pas avoir à reconstituer les endpoints à partir du code frontend. Et qui se heurte à une limite de débit doit savoir à l’avance où elle se situe.
Les endpoints internes sont volontairement absents de la spécification : invalidation du cache, table des redirections, champs de la protection antispam.
Ressources
Des URL fixes. Elles ne changent pas.
| URL | Usage |
|---|---|
| /mcp | Serveur MCP pour la base de connaissances et la vérification de sites web. Streamable HTTP, révision 2026-07-28 et 2025-11-25 ou antérieures, POST uniquement. |
| /openapi.json | OpenAPI 3.1, JSON. Tous les endpoints publics avec schémas, operationId et codes d’erreur. |
| /api/openapi.yaml | La même spécification en YAML. |
| /llms.txt | Structure du site en prose : services, base de connaissances, études, par langue. |
| /llms-full.txt | Version longue avec un aperçu du contenu plutôt qu’une simple liste de liens. |
| /sitemap-index.xml | Liste complète des URL, découpée en lots. |
| /feed.xml | Flux RSS des articles du blog. |
| /robots.txt | Règles pour les crawlers, y compris le signal Content-Signal (ai-train=no). |
Authentification
Aucune. Les endpoints publics n’utilisent ni clés, ni tokens, ni comptes.
Deux d’entre eux ne se prêtent pourtant pas à l’automatisation : le formulaire de contact et l’audit SEO exigent un token que seule la page génère dans le navigateur. La spécification les marque comme browser-only. Un 200 n’y signifie d’ailleurs pas que la requête a été traitée. Les requêtes détectées comme automatisées reçoivent la même réponse que les vraies.
Quotas
Les endpoints soumis à une limite de débit indiquent leur état dans chaque réponse, pas seulement dans le 429. Si tu lis les en-têtes, tu n’as pas besoin de foncer dans le mur pour connaître la limite.
Deux formats sont envoyés côte à côte : RateLimit et RateLimit-Policy selon le projet de l’IETF draft-ietf-httpapi-ratelimit-headers-11, plus les en-têtes historiques RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset, que lisent la plupart des bibliothèques clientes. En août 2026, ce projet n’est pas un RFC.
Quand plusieurs quotas s’appliquent, comme pour le chat par IP et par session, les deux premiers en-têtes les indiquent tous. Les en-têtes historiques n’indiquent que le plus restrictif.
En-têtes de réponse d’un appel au chat
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
- Requêtes autorisées dans la fenêtre.
- w
- Durée de la fenêtre en secondes.
- r
- Requêtes encore disponibles.
- t
- Secondes avant la réinitialisation. Un delta, pas un horodatage.
Serveur MCP
La base de connaissances et la vérification de sites web sont aussi accessibles sous forme de serveur MCP, via POST /mcp. Un assistant qui s’y connecte parcourt les articles, récupère les textes complets sans parser de HTML et vérifie si des sites web publics sont prêts pour les agents IA.
Le transport est Streamable HTTP. L’endpoint sert deux générations du protocole sur la même URL. La révision 2026-07-28 a rendu le cœur sans état : pas de handshake initialize, pas d’ID de session, pas d’endpoint GET. Chaque requête est un POST autonome et porte sa version de protocole dans l’en-tête MCP-Protocol-Version. Mcp-Method est aussi obligatoire, de même que Mcp-Name pour tools/call ; si ces en-têtes ne correspondent pas au corps, la requête est rejetée.
Les clients qui utilisent 2025-11-25, 2025-06-18 ou 2025-03-26 commencent en revanche par initialize et omettent les nouveaux en-têtes. Le SDK officiel en est encore à 2025-11-25 dans sa version 1.30.0, c’est donc aujourd’hui la voie habituelle. Là non plus, aucune session n’est créée : le serveur n’émet pas de Mcp-Session-Id et chaque POST est indépendant. Une version qui ne figure sur aucune des deux listes est rejetée avec -32022 et la liste des révisions prises en charge.
Sans inscription. Le quota est le même que pour les autres endpoints, et les contenus peuvent être réutilisés en citant la source.
| Outil | Description |
|---|---|
| search_knowledge_base | Recherche plein texte dans le titre, la définition courte et le mot-clé principal des articles de la base de connaissances de Blck Alpaca (SEO, GEO, agents IA, automatisation marketing). Renvoie des résultats avec URL et triplet de chemin ; get_knowledge_article récupère le texte complet. |
| list_knowledge_categories | Renvoie la structure de la base de connaissances : toutes les catégories avec leurs thèmes, chacun avec slug et URL. Point d’entrée quand aucun terme de recherche n’est connu. |
| list_knowledge_topic_articles | Tous les articles publiés d’un thème. Le slug de catégorie et le slug de thème doivent correspondre et provenir de la même langue ; sinon, la réponse explique pourquoi. |
| get_knowledge_article | Texte complet d’un article de la base de connaissances en Markdown, avec la définition courte, les points clés, les statistiques sourcées et la FAQ. Le triplet de chemin provient de search_knowledge_base ou de list_knowledge_topic_articles. |
| audit_website | Vérifie si un site web public est prêt pour les agents et pour le GEO : les agents IA peuvent-ils l’atteindre, le lire, le comprendre et agir dessus ? Charge le site comme le ferait un agent (GET uniquement, sans connexion, sans modification) et évalue cinq domaines. Renvoie le score global, les scores par domaine, les trois constats les plus déterminants avec le guide correspondant, chaque contrôle individuel et un lien vers le rapport complet. Pas d’évaluation juridique. |
Lister les outils
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"}'Référencé dans Official MCP Registry at.blckalpaca/knowledge-base · Smithery blckalpaca/knowledge-base
Le connecter à ton assistant IA
Une seule adresse pour tous : https://blckalpaca.at/mcp, sans inscription et sans clé. Ton assistant dispose ensuite des outils de la base de connaissances et de la vérification de sites web (audit_website).
Les chemins de menu proviennent de la documentation de chaque éditeur, à jour en octobre 2026. Si un éditeur modifie son interface, sa documentation fait foi.
Claude (web et desktop)
- Ouvre Customize → Connectors, clique sur « + Add » puis sur « Add custom connector ».
- Saisis « Blck Alpaca » comme nom et https://blckalpaca.at/mcp comme URL, confirme deux fois avec « Continue » et termine avec « Add ». Aucune authentification n’est nécessaire.
- Dans le chat, ouvre « + » → « Connectors » et active l’interrupteur de Blck Alpaca.
Disponible dans toutes les formules ; la formule Free autorise un connecteur personnalisé. En Team et Enterprise, un Owner l’ajoute d’abord dans Organization settings → Connectors.
Claude Code
claude mcp add --transport http blckalpaca https://blckalpaca.at/mcp- Exécute cette commande dans ton terminal. Dans une session, /mcp indique si la connexion est établie.
ChatGPT
- Dans ChatGPT Plugins, clique sur « + » puis sur « Add custom MCP server ».
- Saisis un nom et une description, indique l’URL https://blckalpaca.at/mcp sous « Connection », ne sélectionne aucune authentification et termine avec « Create as a plugin ».
- Dans le chat, tape « @ » et sélectionne Blck Alpaca.
Perplexity
- Dans les paramètres de ton compte, ouvre « Connectors », clique sur « + Custom connector » et choisis « Remote ».
- Saisis un nom et l’URL https://blckalpaca.at/mcp, avec l’authentification « None ».
Pour les comptes Pro, Max et Enterprise. En Enterprise, un administrateur doit d’abord autoriser les connecteurs personnalisés.
Grok
- Ouvre grok.com/connectors, choisis « New Connector » puis « Custom ».
- Saisis l’URL https://blckalpaca.at/mcp. Grok détecte les outils tout seul et les utilise quand une question s’y prête.
Dans Grok Business et Enterprise, un administrateur ajoute d’abord le connecteur dans la console xAI.
Antigravity (CLI, IDE et 2.0)
{
"mcpServers": {
"blckalpaca": {
"serverUrl": "https://blckalpaca.at/mcp"
}
}
}- Ajoute l’entrée dans ~/.gemini/config/mcp_config.json, ou dans .agents/mcp_config.json pour un seul projet. La CLI, l’IDE et Antigravity 2.0 lisent le même format.
- Sans modifier de fichier : dans la CLI, /mcp ouvre le gestionnaire MCP ; dans Antigravity 2.0, passe par Settings → Customizations → Installed MCP Servers → Add MCP.
Antigravity exige « serverUrl ». Les champs « url » et « httpUrl » de Gemini CLI ne sont pas pris en charge. Depuis le 18 juin 2026, Antigravity CLI (agy) remplace Gemini CLI pour les comptes gratuits et les abonnements Google One comme Google AI Pro.
Gemini CLI
gemini mcp add --transport http -s user blckalpaca https://blckalpaca.at/mcp- Exécute cette commande dans ton terminal. Sans « -s user », l’entrée ne vaut que pour le projet en cours. Dans une session, /mcp affiche l’état.
Désormais réservé aux comptes Enterprise et à l’usage avec une clé API payante ; tous les autres utilisent Antigravity. Si tu modifies settings.json toi-même : l’entrée sous mcpServers a besoin de « httpUrl », pas de « url ». « url » est prévu pour l’ancien transport SSE.
Autres clients
- Tout client compatible Streamable HTTP fonctionne : type de serveur HTTP, adresse https://blckalpaca.at/mcp, aucun en-tête. Les clients limités à l’ancien transport SSE ne sont pas pris en charge.
Dépannage
Les écueils les plus fréquents lors de la connexion, avec leur cause et leur solution.
- L’assistant indique que la configuration a échoué.
- Le serveur ne parle que Streamable HTTP en POST, à partir de la révision MCP 2025-03-26. Les clients qui attendent un endpoint GET ou l’ancien transport SSE échouent ici. L’URL doit être exactement https://blckalpaca.at/mcp : avec une barre oblique finale, le serveur répond par une redirection que tous les clients ne suivent pas.
- Réponse 403 ou page de vérification au lieu de JSON.
- La protection anti-bots de Cloudflare a intercepté la requête. Cela arrive parfois aux programmes qui appellent depuis des centres de données. Écris à office@blckalpaca.at en indiquant l’heure et le client, et nous vérifierons les journaux.
- Réponse 429.
- Chaque adresse IP a droit à 240 requêtes par heure. L’en-tête Retry-After indique combien de temps attendre ; RateLimit donne l’état du quota dans chaque réponse. La vérification de sites web a ses propres limites : dix vérifications par heure pour un même site et 60 au total. Au-delà, l’outil répond avec rate_limited.
- Des outils manquent ou affichent d’anciennes descriptions.
- Beaucoup d’assistants enregistrent la liste des outils au moment de la connexion. Déconnecte le connecteur et reconnecte-le.
- La vérification de sites web refuse une adresse.
- Seuls les sites web publics en http ou https sont vérifiés. Les adresses IP privées, les noms d’hôte internes, les noms sans extension de domaine et les adresses impossibles à résoudre sont refusés avec target_not_allowed.
- Un site protégé contre les bots obtient un mauvais score en accès.
- Si sa protection anti-bots bloque notre vérification, elle bloque en général aussi les agents IA. C’est alors un constat, pas un défaut de l’outil.
- Un article manque en français.
- Le serveur omet les contenus non traduits plutôt que de les servir en allemand. Avec locale « de », tu trouves l’article dans sa langue d’origine.
Endpoints
Tableau généré à partir de la même spécification que celle servie sur /openapi.json. Il ne peut pas devenir obsolète.
| Endpoint | operationId | Description |
|---|---|---|
| GET /api/knowledge-search | searchKnowledgeBase | Rechercher dans la base de connaissancesRecherche plein texte dans le titre, la définition et le mot-clé principal des articles de la base de connaissances. |
| GET /api/health | getHealth | Statut de l’applicationPour le monitoring. |
| POST /api/contact | submitContactForm | Envoyer une demande de contactDéclenche un e-mail de confirmation en double opt-in. |
| POST /api/newsletter/subscribe | subscribeNewsletter | S’abonner à la newsletterDouble opt-in. |
| POST /api/newsletter/unsubscribe | unsubscribeNewsletter | Se désabonner de la newsletterAttend le token du lien de désabonnement de l’e-mail. |
| GET /api/newsletter/unsubscribe/validate | validateUnsubscribeToken | Vérifier un token de désabonnementVérifie si un token de désabonnement est valide sans effectuer le désabonnement. |
| GET /api/newsletter/verify | verifyNewsletterSubscription | Confirmer l’inscription à la newsletterCible du lien de l’e-mail de confirmation. |
| GET /api/contact/verify | verifyContactRequest | Confirmer une demande de contactCible du lien de l’e-mail de confirmation. |
| GET /api/chat | getChatSession | Consulter l’historique d’une session de chat (rédaction uniquement)Exige une connexion au CMS. |
| POST /api/chat | sendChatMessage | Message à l’assistant du siteLimite de débit par IP et, en plus, par session. |
| GET /api/agentic-check | runAgenticCheck | Vérifier si un site web est prêt pour les agentsVérifie un site web accessible publiquement dans cinq domaines pondérés : accès 30, compréhension 25, découvrabilité 20, transparence UE et confidentialité 15, capacité d’action 10. |
| POST /api/agentic-check | runAgenticCheckPost | Vérifier si un site web est prêt pour les agents (via le formulaire)Identique à GET, mais avec les données dans le corps. |
| GET /api/agentic-check/result/{token} | getAgenticCheckResult | Récupérer un résultat enregistréRenvoie un résultat déjà produit sans solliciter à nouveau les serveurs vérifiés. |
| POST /api/agentic-check/report | requestAgenticReport | Demander le rapport détaillé par e-mail (navigateur uniquement)Exige un challenge token issu du formulaire. |
| POST /api/seo-audit | requestSeoAudit | Demander un audit SEO gratuit (navigateur uniquement)Exige un challenge token généré dans le navigateur au chargement du formulaire. |
Réponses d’erreur
Chaque erreur a la même forme : error porte un code stable, message le texte destiné aux humains, hint indique quoi faire. Les codes ne sont jamais renommés ni réutilisés pour autre chose. Ton code peut s’appuyer dessus dans ses conditions.
| Code | Statut | Conseil |
|---|---|---|
| VALIDATION_ERROR | 400 | Vérifie `fields` dans cette réponse : l’erreur concrète y figure pour chaque champ. |
| INVALID_REQUEST | 400 | Le plus souvent, un challenge token manquant ou expiré. Recharge la page et renvoie le formulaire. |
| MISSING_FIELDS | 400 | Complète les champs indiqués dans `fields` et renvoie la requête. |
| MISSING_EMAIL | 400 | Envoie `email` dans le corps JSON. |
| FIELD_TOO_LONG | 400 | Raccourcis le champ indiqué dans `fields`. |
| MALFORMED_BODY | 400 | Envoie un JSON valide et définis `Content-Type: application/json`. |
| INVALID_EMAIL | 400 | Adresse attendue au format nom@domaine.tld. |
| INVALID_EMAIL_DOMAIN | 400 | Le domaine n’a pas d’enregistrement MX. Utilise une autre adresse. |
| DISPOSABLE_EMAIL | 400 | Utilise une adresse permanente. Ne réessaie pas avec la même adresse. |
| ALREADY_SUBSCRIBED | 400 | Inutile de réessayer : l’état est déjà celui que tu voulais. |
| INVALID_URL | 400 | URL absolue attendue, avec http:// ou https://. |
| INVALID_WEBSITE | 400 | Domaine joignable attendu. |
| GDPR_REQUIRED | 400 | Mets `gdprConsent` à true. Sans consentement, rien ne peut être enregistré. |
| INVALID_TOKEN | 400 | Les tokens sont à usage unique. Demandes-en un nouveau. |
| TOKEN_EXPIRED | 410 | Demande un nouveau token via l’endpoint d’origine. |
| METHOD_NOT_ALLOWED | 405 | Les méthodes autorisées figurent dans l’en-tête `Allow` de cette réponse. |
| NOT_FOUND | 404 | Vérifie le chemin. Une vue d’ensemble du site se trouve sur /llms.txt. |
| UNAUTHORIZED | 401 | Cet endpoint est interne et attend un secret valide. |
| RATE_LIMIT | 429 | Attends le nombre de secondes indiqué dans l’en-tête `Retry-After`. `RateLimit` indique le quota restant ; cet en-tête figure aussi dans les réponses réussies. |
| EMAIL_LIMIT | 429 | La limite s’applique par adresse, pas par IP. Changer d’IP ne sert à rien. Cette limite est volontairement absente de l’en-tête `RateLimit`. |
| SPAM_REJECTED | 400 | Ne réessaie pas. En cas d’erreur d’appréciation, signale-le par e-mail à office@blckalpaca.at. |
| UPSTREAM_UNAVAILABLE | 503 | Temporaire. Il est judicieux de réessayer avec un backoff exponentiel. |
| INTERNAL_ERROR | 500 | Ta requête n’en est pas la cause. Réessaie plus tard. |
Exemples
Deux appels qui fonctionnent sans navigateur.
Rechercher dans la base de connaissances
curl "https://blckalpaca.at/api/knowledge-search?q=schema&locale=fr"Consulter le statut
curl -i "https://blckalpaca.at/api/health"Quelque chose manque ou est faux
Si un endpoint répond autrement que décrit ici, c’est la description qui est fausse. Un court message suffit.
Contact