Aller au contenu
01Développeurs

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.

URLUsage
/mcpServeur 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.jsonOpenAPI 3.1, JSON. Tous les endpoints publics avec schémas, operationId et codes d’erreur.
/api/openapi.yamlLa même spécification en YAML.
/llms.txtStructure du site en prose : services, base de connaissances, études, par langue.
/llms-full.txtVersion longue avec un aperçu du contenu plutôt qu’une simple liste de liens.
/sitemap-index.xmlListe complète des URL, découpée en lots.
/feed.xmlFlux RSS des articles du blog.
/robots.txtRè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.

OutilDescription
search_knowledge_baseRecherche 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_categoriesRenvoie 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_articlesTous 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_articleTexte 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_websiteVé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)

  1. Ouvre Customize → Connectors, clique sur « + Add » puis sur « Add custom connector ».
  2. 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.
  3. 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
  1. Exécute cette commande dans ton terminal. Dans une session, /mcp indique si la connexion est établie.

ChatGPT

  1. Dans ChatGPT Plugins, clique sur « + » puis sur « Add custom MCP server ».
  2. 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 ».
  3. Dans le chat, tape « @ » et sélectionne Blck Alpaca.

Perplexity

  1. Dans les paramètres de ton compte, ouvre « Connectors », clique sur « + Custom connector » et choisis « Remote ».
  2. 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

  1. Ouvre grok.com/connectors, choisis « New Connector » puis « Custom ».
  2. 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"
    }
  }
}
  1. 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.
  2. 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
  1. 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

  1. 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.

EndpointoperationIdDescription
GET /api/knowledge-searchsearchKnowledgeBaseRechercher 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/healthgetHealthStatut de l’applicationPour le monitoring.
POST /api/contactsubmitContactFormEnvoyer une demande de contactDéclenche un e-mail de confirmation en double opt-in.
POST /api/newsletter/subscribesubscribeNewsletterS’abonner à la newsletterDouble opt-in.
POST /api/newsletter/unsubscribeunsubscribeNewsletterSe désabonner de la newsletterAttend le token du lien de désabonnement de l’e-mail.
GET /api/newsletter/unsubscribe/validatevalidateUnsubscribeTokenVérifier un token de désabonnementVérifie si un token de désabonnement est valide sans effectuer le désabonnement.
GET /api/newsletter/verifyverifyNewsletterSubscriptionConfirmer l’inscription à la newsletterCible du lien de l’e-mail de confirmation.
GET /api/contact/verifyverifyContactRequestConfirmer une demande de contactCible du lien de l’e-mail de confirmation.
GET /api/chatgetChatSessionConsulter l’historique d’une session de chat (rédaction uniquement)Exige une connexion au CMS.
POST /api/chatsendChatMessageMessage à l’assistant du siteLimite de débit par IP et, en plus, par session.
GET /api/agentic-checkrunAgenticCheckVé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-checkrunAgenticCheckPostVé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}getAgenticCheckResultRé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/reportrequestAgenticReportDemander le rapport détaillé par e-mail (navigateur uniquement)Exige un challenge token issu du formulaire.
POST /api/seo-auditrequestSeoAuditDemander 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.

CodeStatutConseil
VALIDATION_ERROR400Vérifie `fields` dans cette réponse : l’erreur concrète y figure pour chaque champ.
INVALID_REQUEST400Le plus souvent, un challenge token manquant ou expiré. Recharge la page et renvoie le formulaire.
MISSING_FIELDS400Complète les champs indiqués dans `fields` et renvoie la requête.
MISSING_EMAIL400Envoie `email` dans le corps JSON.
FIELD_TOO_LONG400Raccourcis le champ indiqué dans `fields`.
MALFORMED_BODY400Envoie un JSON valide et définis `Content-Type: application/json`.
INVALID_EMAIL400Adresse attendue au format nom@domaine.tld.
INVALID_EMAIL_DOMAIN400Le domaine n’a pas d’enregistrement MX. Utilise une autre adresse.
DISPOSABLE_EMAIL400Utilise une adresse permanente. Ne réessaie pas avec la même adresse.
ALREADY_SUBSCRIBED400Inutile de réessayer : l’état est déjà celui que tu voulais.
INVALID_URL400URL absolue attendue, avec http:// ou https://.
INVALID_WEBSITE400Domaine joignable attendu.
GDPR_REQUIRED400Mets `gdprConsent` à true. Sans consentement, rien ne peut être enregistré.
INVALID_TOKEN400Les tokens sont à usage unique. Demandes-en un nouveau.
TOKEN_EXPIRED410Demande un nouveau token via l’endpoint d’origine.
METHOD_NOT_ALLOWED405Les méthodes autorisées figurent dans l’en-tête `Allow` de cette réponse.
NOT_FOUND404Vérifie le chemin. Une vue d’ensemble du site se trouve sur /llms.txt.
UNAUTHORIZED401Cet endpoint est interne et attend un secret valide.
RATE_LIMIT429Attends 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_LIMIT429La 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_REJECTED400Ne réessaie pas. En cas d’erreur d’appréciation, signale-le par e-mail à office@blckalpaca.at.
UPSTREAM_UNAVAILABLE503Temporaire. Il est judicieux de réessayer avec un backoff exponentiel.
INTERNAL_ERROR500Ta 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