API Documentation for AI Agents

An agent reading your documentation is doing what a new developer does, with two differences. It cannot ask a colleague, and it will not scroll past a wall of navigation to find the sentence that matters.

That makes this a formatting problem before it is anything else.

What an agent actually receives

When an assistant fetches a documentation page, it gets HTML. Inside that HTML the useful content is wrapped in navigation, a sidebar, a cookie banner and whatever the framework emitted.

Converting that back to clean text is possible and lossy. Tables come out mangled, code blocks lose their language, and the parts that carried meaning visually lose it entirely. Every wasted token also costs context that the agent needed for your actual content.

So the first thing an agent-friendly documentation site does is offer the content without the page around it.

The two conventions worth following

The llms.txt proposal covers both halves, and it is a proposal rather than a web standard, retrieved 2026-09-13.

The first half is an index. A file at /llms.txt carries a short description of the site and a curated list of links, so an agent that lands on your root can see the shape of the documentation without crawling it. The file stays small on purpose, because it is meant to fit in a context window while the detail waits behind the links.

The second half is a Markdown version of each page, served next to the HTML. The proposal suggests appending .md to the URL, or index.md where the URL has no filename. An agent that follows a link from the index then gets the content rather than the chrome.

A single-file variant is common as well, where the whole site is concatenated into one Markdown document. It suits an agent that would otherwise fetch twenty pages one at a time.

Generated reference pages have to be text

This is where documentation platforms usually fall down, and it is worth checking on your own site.

Written pages are easy, because they were Markdown before they were HTML. Generated endpoint pages are not, since they are often assembled from a schema at render time into a component tree that has no text representation at all. The result is a site where the guides are readable and the reference, which is the part an agent needs most, is a blank.

A generated endpoint page that serves properly needs its path, its method, its parameters, its bodies and its errors written out as text. Schema references have to be resolved rather than left as pointers an agent would follow and reassemble.

Robots and discovery

An agent that has not been told where your index lives has to guess, and robots.txt is the file it already reads.

Point it at your sitemap and at your llms.txt, which costs one line each. The llms.txt proposal also describes link relations that let a page advertise its own Markdown twin, using rel="alternate" with the Markdown media type.

The writing still decides the outcome

Formatting gets the content to the agent. It does not make the content good.

Everything in how to write API reference documentation applies twice over here, because an agent has no intuition to fall back on. A summary that restates the endpoint name leaves it choosing between two operations that look identical, and an enum without meanings leaves it guessing what a status value implies.

Reading is only half of it

Everything above assumes the agent is a consumer of your documentation. The other case is an agent that maintains it.

An assistant that can read the content tree, write a page, and publish a version is doing the same job a technical writer does, under the same permissions and with the same review step. That is worth setting up carefully rather than quickly, since documentation is a publishing surface and an agent with write access to it is publishing on your behalf.

In Routebase

Every portal build in Routebase emits the machine-readable outputs alongside the HTML, and they are not a switch you turn on. A build that fails to produce them fails. The product page for agent-ready APIs puts these files next to the descriptions and errors an agent reads first.

There is an index at /llms.txt, a single-document version of the whole portal at /llms-full.txt, and a Markdown twin at {slug}/index.md for every page. Reference pages emit generated Markdown covering the path, the method, the parameters and both bodies with schema references resolved, so an endpoint page is readable as text rather than only as a rendered widget. The robots.txt of the portal points at the sitemap and at the index.

Our own product documentation runs on this, so the files are open to check rather than to take on trust. The index, the full document and the Markdown twin of any page all answer right now.

Readers get the same thing through the page actions menu, which offers the page as Markdown, the OpenAPI document as a download, and a hand-off into an assistant. Beyond that, the documentation module is reachable over the Routebase MCP server, so an agent can read the content tree, write pages into a draft version and publish it under the permissions its key carries. The Publishing guide documents the emitted files, and the Documentation Overview covers the agent side.