Making Our API Docs Available as Markdown for Coding Agents (llms.txt, Accept Headers)
This post was drafted with AI assistance and reviewed by the PerfectVector team.
An HTML documentation page can carry far more than its documentation text. We checked what our own "API for AI agents" page sends when you fetch it, and what we publish alongside it. All numbers are from 2026-11-13. They measure response sizes, not model tokens, cost or whether an agent does better with them; we haven't tested that.
What a plain fetch returns
The page requested as HTML: 370,609 bytes. By a simple regex for <script>…</script> blocks, about 308,600 of those bytes are script tags (the framework's data payload; the exact figure shifts slightly between fetches). The visible text is about 11,600 characters.
What we publish instead
- A Markdown twin of each doc page (listed in a catalog). The same page at
/docs/api/agents.mdis 12,290 bytes and has the endpoint table, errors and a full example. In this recording the HTML response was 30.2 times the size of the Markdown one. - Content negotiation. The HTML URL answers
Accept: text/markdownwithContent-Type: text/markdown, so a client doesn't need to know the.mdconvention:
curl -s -H "Accept: text/markdown" https://perfectvector.com/docs/api/agents
/llms.txt, 3,950 bytes: one sentence on what the product is, then links to the Markdown versions of the product facts, pricing, API reference and MCP docs. The HTML pages advertise it withLink: </llms.txt>; rel="describedby"./llms-full.txtand/docs/catalog.json: a list of every documentation page with its summary, and a machine-readable catalog of published documents with versions and review dates.- A page written for agents. The agents page puts keys, endpoints, prices, limits, errors and a runnable example in one document, so the information for a first integration is in one document.
Writing choices beyond the format
- Tables for anything a client will branch on: endpoints, status codes, retry rules.
- Stable error code values documented as the thing to branch on, with detail called out as not for parsing.
- Document versions and review dates exposed in the catalog.
What we're not sure about
We haven't verified which crawlers or agents fetch llms.txt, the Markdown twins or the Accept negotiation. Server logs could show requests for these files, but wouldn't by themselves show how an agent used them. We publish them anyway; any effect on agent accuracy remains untested.
To try this on your own docs, start by checking what a plain curl of your docs page returns, and how much of it is script.
Docs for agents: PerfectVector API for AI agents. We build PerfectVector, an image-to-vector tool.
Comments
No comments yet. Start the discussion.