On this page
As of November 2026, many developers ask an AI coding agent to write the code that calls your API, and the agent learns your API from your docs. Docs that agents can use have a full reference, examples that run as written, plain steps for authentication, a list of errors with what to do next, and no old examples mixed into current pages. They must also be readable without JavaScript.
Use three kinds of pages, and keep them apart
| Page type | It answers | Keep in it |
|---|---|---|
| Reference | What exactly does this endpoint take and return? | Every parameter, type, default, limit and response field |
| Use-case guide | How do I get this job done? | One goal, the calls in order, and why each one is needed |
| Integration tutorial | How do I connect this to the tool I use? | Prerequisites first, then numbered steps that end in a working result |
Mixing them in one page makes the agent guess which part applies. Link between them instead.
Write examples that run as written
- Show the full request: method, URL, headers and body.
- Use placeholder names that look like placeholders, such as YOUR_API_KEY.
- Show the full response, including the fields people need next.
- Test every example against the live API when you release a version.
Make authentication plain
- Say which method each endpoint uses: API key, OAuth or session.
- Show where the credential goes in the request, with one example.
- List the scopes or permissions each endpoint needs.
- Say how to get a test key, and how a key is rotated or revoked.
Document errors as next steps
For each error, give the status code, the error code in the body, what it means and what to do. Agents use this to recover without a person. A standard shape, such as Problem Details for HTTP APIs, makes errors easy to parse.
Keep old versions out of current pages
- Put each API version's docs at its own address.
- Mark deprecated endpoints clearly, with the date and the replacement.
- Remove old examples from current guides instead of adding notes around them.
- Publish a machine-readable description, such as an OpenAPI file, for the current version.
Make the docs reachable
- Serve docs as HTML that does not need JavaScript to show the text.
- Give each page its own title and canonical address, and put it in your sitemap.
- Add an llms.txt file that points to the reference, the main guides and the OpenAPI file.
Questions people ask
Do AI agents read OpenAPI files?
Many tools can import an OpenAPI file to learn an API. It helps people and tools, and it keeps the reference exact.
Should docs sit behind a login?
Public docs should not. An agent or crawler that cannot sign in cannot read them.
How do I know if agents get my API wrong?
Ask an AI coding agent to write a call to your API from a plain request, and compare the result with your reference.
What this does not tell you
Which of your docs pages AI crawlers can read today, and which pages AI assistants cite when developers ask about your category.
Sources
- 1.OpenAPI Initiative: the OpenAPI format for describing HTTP APIs
- 2.RFC 9457: Problem Details for HTTP APIs: a standard shape for API error responses
- 3.llmstxt.org: the llms.txt proposal