Most of Your Docs Readers Are Now AI Agents: Writing API Docs They Can Use

The shift, and what the evidence actually says

The title comes from a talk by Hahnbee Lee of Mintlify and Lincoln Murr of Coinbase, published on the AI Engineer YouTube channel. This page does not summarize the talk and attributes nothing to it beyond its title. The supporting data below comes from published sources.

Mintlify's State of Knowledge 2026 highlights, published September 16, 2026, report that in August 2026 agents made 257 million requests to the docs sites it hosts, against 131 million human page loads, nearly two to one. Of that agent traffic, it puts 83% on the machine-readable paths rather than on rendered HTML. In a benchmark of 2,400 controlled tests across 20 documentation sites, average 404 errors per task were 2.23 on HTML, 1.42 on Markdown and 0.11 on Markdown with llms.txt, and adding llms.txt cut token use by up to 60%.

These are a docs vendor's own numbers, and the highlights do not explain how agent traffic was identified. The practical conclusion holds regardless: agents read docs differently from people, and pages built only for people fail them in measurable ways.

Give agents an index and a clean copy of every page

Publish llms.txt. The format, proposed by Jeremy Howard in September 2024, is a Markdown file at /llms.txt, or at a subpath such as /docs/llms.txt covering that section. An H1 with the project name is the only required element. A blockquote summary follows, then H2 sections that list links as [name](url): notes. A section titled Optional, by convention, holds links an agent can skip when it is short on context.

Serve a Markdown twin of each page. The proposal suggests a clean Markdown version at the same URL with .md appended, as page.html.md or page.md, and in practice sites also advertise it with a rel="alternate" type="text/markdown" link or an HTTP Link header. Markdown strips the navigation, scripts and layout that cost an agent tokens and make it guess.

Both x402 documentation sites already do this. As checked on November 4, 2026, docs.x402.org/llms.txt indexes the protocol docs with .md links, and docs.cdp.coinbase.com/llms.txt indexes Coinbase's developer docs, including its x402 pages.

Make pricing machine-readable

A pricing table built for a human tells an agent that a price exists, not what it will be asked to pay. An agent deciding whether to call needs the price per unit, the asset, the network and how the charge is computed, in a form it can compare against a budget.

In x402 the authoritative price is the 402 response itself. Its accepts array gives amount in atomic token units, asset as a contract address, network as a CAIP-2 identifier such as eip155:8453 for Base, payTo and maxTimeoutSeconds. Your docs should state the same facts per route and explain the units: with USDC's six decimals, an amount of 10000 is one cent. Say which scheme applies. Under exact the amount is the price. Under upto it is a maximum, and the settled amount reflects usage.

If you list endpoints in a Bazaar catalog, the bazaar extension in your 402 carries input and output schemas too. Docs, the live 402 and the catalog entry should agree. When they diverge, the agent will trust whichever it read last.

Document the payment flow, not just the endpoint

Agent-facing x402 docs should answer, on one page:

• Which routes are paid, and which are free, including any free preview or health check.
• What each costs and under which scheme, networks and assets.
• The headers. PAYMENT-REQUIRED on the 402, PAYMENT-SIGNATURE on the retry and PAYMENT-RESPONSE on success in v2, plus the v1 header names if you still serve v1 clients; the v2 transport spec has a compatibility section covering that case.
• A decoded example of your real 402 body, not only the base64 string.
• Error reasons your facilitator returns, such as insufficient_funds, by code. Match on the code rather than the message text, since the text is free-form and the code is not.
• Retry and failure behavior. What happens if payment settles and the handler fails, and whether a retry pays again.
• A testnet path, for example the same route on Base Sepolia, so an agent can complete the whole flow without real funds.

Put a working request first. An agent that can copy a correct curl and a correct decoded challenge needs far less prose than one reconstructing the flow from narrative.

Write for a reader that cannot ask

An agent cannot open a support ticket or infer intent from a screenshot. Make each page self-contained, keep URLs stable (the 404 benchmark above is a broken-link cost), keep critical information out of images and client-rendered tabs, and version anything that changes behavior.

Accuracy also carries more weight. Mintlify's report quotes Sarah Deaton of Anthropic: "The same page that misled one developer now misleads an unknowable number of agents." For a paid API the wrong price or the wrong network in docs is not a typo. It is a payment an agent may sign.

On the buyer side, that is why the price check belongs in code. An agent paying from a CryptoCadet float, where the spending ceiling lives in the session key rather than in the prompt, compares the live 402 against that ceiling before signing, whatever the docs said.