Une documentation qu'un agent peut lire.

Le lecteur d’ApiGlow peut être une personne — ou un agent, ou une personne qui travaille avec un agent. L’app produit dans le navigateur tout ce que ce lecteur-là emporte : cette documentation ne fait tourner aucun serveur, il n’y a donc nulle part ailleurs où le produire, et aucun modèle n’est jamais appelé. Chaque chose s’attrape là où on la veut — les fichiers de l’API entière depuis l’accueil et la navigation, ceux d’un endpoint depuis le menu « Copier la page » de l’opération. La version courte vit sur la page Surface IA ; ce guide est le mode d’emploi.

Générer les deux fichiers texte

llms-full.txt est la documentation entière en un seul document Markdown — infos du schéma, pages de prose, chaque opération — le format que les assistants ingèrent d’un bloc. Générez-le depuis la page d’accueil, ou depuis le menu « Copier la page » de n’importe quelle opération.

llms.txt est l’index du même contenu, selon la convention llmstxt.org : les pages de doc sous le titre de leur groupe de nav (celles de la zone du haut en ## Guides, celles de la zone du bas en ## Resources), une section ## Workflows qui liste chaque scénario déclaré en config avec ses nombres d’étapes et d’entrées — et sa recette Arazzo quand elle est publiée —, un lien par opération groupée par tag, un par webhook, plus où trouver le texte complet et le fichier OpenAPI. L’en-tête énonce l’URL de base et une ligne d’orientation sur les schemes d’auth, et le lien Reference est qualifié honnêtement : quand la documentation rend le schéma à travers des overlays, ou cache des opérations que le fichier publié déclare toujours, le lien le dit — un agent qui lit le fichier brut mérite de savoir qu’il diffère de ce que voient les humains. llms.txt ferme aussi la section documentation de la navigation — en bouton, pas en lien : le fichier se génère sur place, il n’y a aucune page vers laquelle naviguer.

Les héberger à côté de la page

La doc est une application routée par hash : un crawler ou un LLM ne peut pas parcourir des URL #/op/…. C’est exactement ce que ces deux fichiers corrigent — à condition d’être atteignables. Déposez-les à côté de la page hôte et servez-les statiquement à la racine du site :

docs.example.com/
├── index.html      ← la page qui porte la balise script ApiGlow
├── llms.txt
└── llms-full.txt

Ou laisser le bake les servir

Télécharger et copier à la main fonctionne ; apiglow bake l’automatise. Le CLI écrit llms.txt et llms-full.txt en fichiers servis, dans le même passage qui écrit les miroirs HTML et Markdown — et les versions servies valent mieux que les téléchargements : llms.txt pointe vers le miroir .md servi de chaque page au lieu de routes à fragment qu’un agent ne peut pas récupérer, et chaque section de llms-full.txt porte une ligne Source: vers sa page. La génération dans le navigateur garde les liens à fragment : sans bake, il n’y a rien d’autre à pointer.

Les deux fichiers sont des instantanés du document chargé — l’app ne peut pas venir mettre à jour des fichiers sur votre serveur. Quand le schéma change, relancez le bake (ou régénérez à la main) et redéployez avec la page. Si le déploiement de la doc est scripté, c’est une étape de plus dans le job, pas un nouveau pipeline.

La carte de config MCP

Pour les agents qui parlent MCP, la page d’accueil génère aussi une config de serveur prête à coller : elle relie un pont OpenAPI→MCP du commerce — qui tourne sur la machine du lecteur, choisi depuis la carte — à l’URL OpenAPI de cette API. Les credentials en sortent comme des espaces réservés clairement marqués, jamais comme les valeurs stockées dans les environnements de qui que ce soit. Lisez le bloc, collez-le dans la config client de l’agent (Claude Desktop, Claude Code, …), ou téléchargez-le en mcp.json.

Le même enregistrement sort aussi dans les deux autres formes que prend l’outillage d’un lecteur : une ligne de commande claude mcp add … à coller dans un terminal, et des liens d’installation pour Cursor et VS Code qui tendent le tout à l’éditeur. Les trois sont construits depuis une seule config : la commande installe donc exactement ce que dit le bloc sous vos yeux — il n’y a pas de seconde source qui pourrait dériver de la première.

Trois comportements à connaître : la carte propose deux ponts, qui diffèrent sur la prise en charge des overlays — choisir celui qui ne peut pas appliquer les vôtres est signalé, jamais silencieux ; un scheme de sécurité sans forme d’en-tête (un apiKey en query ou en cookie, mutualTLS) est rapporté tel quel plutôt qu’approximé ; et avec un schéma inline (openapi.spec), pas de carte du tout — un pont a besoin d’une URL à télécharger, et la page n’en a aucune à lui tendre. Cette dernière règle vaut aussi pour la commande et les liens d’installation : pas d’URL, pas d’enregistrement, sous aucune forme.

Le menu de transmission, sur chaque endpoint

Les fichiers à emporter ne sont pas réservés à la page d’accueil. Le menu « Copier la page » de chaque opération répond à une seule question — donne-moi cette page ailleurs — sur trois registres, du plus étroit au plus large.

Cet endpoint, en Markdown. Copiez-le dans le presse-papiers, ou ouvrez « Voir en Markdown » pour lire la source d’abord : une boîte de dialogue par-dessus la documentation, qui montre exactement la chaîne que produit la copie, telle quelle dans un <pre>, avec un bouton pour l’enregistrer en {operationId}.md. C’est une vue et non une URL, à dessein — la doc est routée par hash, il n’existe donc aucune adresse ?format=md à donner à qui que ce soit.

Cet endpoint, tendu à un assistant. Deux entrées ouvrent ChatGPT ou Claude dans un nouvel onglet, le Markdown de l’endpoint déjà glissé dans le prompt, sous une phrase qui demande à l’assistant de le lire et d’aider à utiliser l’endpoint. Le Markdown est tronqué au-delà de ~6 000 caractères : les navigateurs plafonnent la longueur d’une URL, et un prompt massacré en silence serait pire qu’un prompt visiblement raccourci.

L’API entière, branchée sur un agent. llms-full.txt, plus l’enregistrement MCP dans ses trois formes. À noter : cette partie-là reste à l’échelle de l’API, même dans le menu d’une opération — ce dont un agent a besoin, c’est du document, et la config ne se restreint jamais à un endpoint. Son URL de base suit l’environnement sélectionné : enregistrer depuis un environnement de sandbox produit un enregistrement de sandbox.