Documentatie gemaakt voor AI-agents, niet alleen voor mensen

Klassieke documentatie is gemaakt voor mensen: gerenderde HTML, syntax highlighting, een zijbalk, zoekfunctie. Maar steeds vaker wordt de documentatie niet door een mens gelezen, maar door een agent (Claude, Cursor, ChatGPT), en die heeft alleen maar last van al die rendering. Een agent heeft pure tekst en een machineleesbaar contract nodig.

We hebben de documentatie geschikt gemaakt voor allebei. Dit zit er onder de motorkap.

Elke pagina van de contentdocumentatie heeft een kale Markdown-tweeling op hetzelfde pad met het achtervoegsel .md. Open je /agent-setup, dan is er ook /agent-setup.md: dezelfde tekst zonder HTML-verpakking, met de MDX-imports eruit gehaald, geserveerd als text/markdown.

Dat voedt twee acties in het paginamenu: Copy as Markdown (zet de pure tekst op het klembord, om in een chat met een model te plakken) en View as Markdown (opent de .md-versie direct). Een agent hoeft geen DOM te parsen: hij pakt de kant-en-klare tekst.

Rechtsboven op elke pagina staat een actiemenu, speciaal gemaakt voor een agent-workflow:

• Copy as Markdown: de pure tekst van de pagina naar het klembord
• View as Markdown: de .md-tweeling openen
• Open in ChatGPT: de pagina met één klik aan ChatGPT doorgeven
• Open in Claude: hetzelfde voor Claude
• Connect MCP: naar de instellingen van de MCP-server

In plaats van “kopieer de URL, open een chat, vraag of hij de pagina bezoekt” is het één actie.

Volgens de standaard llmstxt.org serveren we twee bestanden:

• /llms.txt: een index van alle documentatiepagina’s, gegroepeerd in secties (API Reference, Use Cases, Examples, Products). Een kaart voor de agent: waar begin je.
• /llms-full.txt: de volledige documentatie in één plain-text-bestand. Voor offline indexering in een vectordatabase of om in één keer in de context van een model te plakken.

Bouw je RAG bovenop onze API, dan is llms-full.txt een kant-en-klaar corpus: je hoeft de site niet te crawlen.

Het contract wordt in meerdere formaten geleverd, voor verschillende tools:

• /v1/openapi.json: de canonieke OpenAPI 3.1-specificatie met voorbeelden en code-samples. Voor het genereren van clients en voor alle OpenAPI-tooling.
• Swagger-aliassen: /v1/swagger.json, /v1/v3/api-docs en andere geven een 301-redirect naar de canonieke versie, zodat tools die op gebruikelijke paden zoeken niet struikelen.
• Postman-collectie: /postman/astroway-api.json om met één klik in Postman te importeren.

De pagina /agent-setup/ is geen algemene handleiding, maar een set aparte instructies voor zeven clients: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Elke instructie geeft de exacte configuratie en een curl-voorbeeld van tools/list, zodat je de koppeling kunt controleren voordat je code schrijft.

Op de pagina’s van de API-referentie heeft elke operatie een ingebouwde try-it-widget: je plakt een sandbox-sleutel, bewerkt de request body, klikt op “Send” en ziet een echte response, zonder de docs te verlaten. Methode, pad en voorbeeldbody komen uit de al gegenereerde curl-snippet, dus de widget doet geen extra verzoeken naar openapi.json.

De stelling is eenvoudig: als je product een API is, moet de documentatie niet alleen leesbaar zijn voor het oog, maar ook bruikbaar voor een agent. De helft van de integraties begint tegenwoordig ermee dat een developer een link naar de docs in Claude of Cursor plakt en vraagt “koppel dit”. We hebben ervoor gezorgd dat daar aan de andere kant pure tekst en een machinecontract staan, geen HTML die eerst geparst moet worden.

Probeer het zelf: open een willekeurige pagina van de docs, klik op het actiemenu rechtsboven en je ziet “Open in Claude”.