How to make your API docs legible to AI coding agents

An AI coding agent does not read your documentation. It retrieves two or three pages, extracts what looks like an answer, and writes code from that extract. If your enum values live in a screenshot, your working example needs three paragraphs of context to make sense, or your reference page opens with a sentence about empowering teams, the agent will produce code that does not run and the developer will blame your API.

The useful surprise is that almost everything that makes docs legible to an agent also makes them better for a hurried human. This is not a separate documentation project. It is the same discipline, with the excuses removed.

RocketPrint is a remote printing API and desktop Station for software platforms: your backend POSTs a print job, and a small app beside the printer prints it, with no inbound networking, no drivers for raw label formats, and a durable job record. We pass some of the rules below and fail others, and the failures are named where they come up: we publish an OpenAPI 3.1 description of the API, our reliability page lists the failures we cannot see, and the writing rules in this post are a new standard we are only starting to hold our own pages to.

An agent gets your docs through four surfaces, and you control all of them

The mechanics are worth being concrete about, because the advice changes by surface.

Surface	How it is used	What it rewards
Crawled HTML pages	Fetched at the moment the agent needs them, usually one or two pages deep from a search result or a link the developer pasted	Self-contained pages that answer in the first paragraph
Your OpenAPI document	Parsed as structured ground truth, and often the only thing that cannot be misread	Completeness and accuracy of enums, required fields, and error shapes
llms.txt	Treated as a table of contents by some developer tooling and coding assistants	Being short, being current, and pointing at pages that are actually good
Training data	Whatever was public when the model was trained	Nothing you can influence this quarter

The first two matter most, and the second repays effort fastest. Note also that the agent's context window is a budget. A page that answers in 200 tokens gets quoted. A page that answers in 4,000 gets truncated, and you do not choose where the truncation happens.

llms.txt is worth an afternoon, not a quarter

The honest data first, because this file is being oversold.

One analysis of an SE Ranking study of nearly 300,000 domains put llms.txt adoption at 10.13 percent, and found high-traffic sites adopting it slightly less often than mid-traffic ones. Google's AI guidance of May 15, 2026 says the file is not needed for AI Overviews or AI Mode. If you were told that publishing one improves your visibility in AI search, that is not supported.

What is true: it is used by developer tooling and AI coding assistants, and Anthropic, OpenAI, and Cloudflare publish one. If your audience is developers pointing coding agents at your API, that is exactly the population that fetches it. A short file listing your docs pages, your OpenAPI document, your errors page, and your reference posts, one line each, costs an afternoon and cannot hurt. Do not build a content strategy around it, and do not generate a 3,000-line version of your whole site. Write the table of contents.

We do not publish one today. We are adding one, and the fact that this post explains the format before we have shipped it is a fair thing to hold against us.

Your OpenAPI document is the only thing an agent cannot misread

Prose can be misparaphrased. A schema cannot. If an agent has your OpenAPI document, it knows the required fields, the enum values, the status codes, and the shape of an error, without inference.

The bar is higher than "we have a spec file." It has to be current, include enums in full rather than as type: string, describe error responses, and be linked from every page that mentions the API so a crawler landing on a guide can find it. Ours is an OpenAPI 3.1 document, and the API reference is written from it rather than maintained in parallel, which is the only arrangement that stays true.

A test you can run today: hand an agent nothing but your OpenAPI document and ask it to write a working create call. If it has to guess anything, that gap is in your schema.

Rule 1: answer in the first paragraph, in the words people search with

Put the declarative answer in the first two sentences of the page, using the reader's term rather than your internal one.

Extraction, by a retrieval system or a person scanning, takes the top of the page. A page opening with "Printing has changed a lot in the last decade" has spent its best real estate on nothing. The test: delete everything except the first paragraph. Does what remains answer the question in the page title? If not, rewrite the paragraph, not the page.

Rule 2: one description of the product, verbatim, everywhere

Pick one sentence describing what you are and repeat it exactly, on the site, in the docs, in the README, and in every post that introduces you.

This feels repetitive to an editor who reads every page in a week. It is not repetitive to a retrieval system that sees them one at a time, and consistent phrasing is how a model learns an entity is one thing rather than four vaguely related products. Paraphrasing your own positioning is how you end up described inaccurately in an answer you cannot edit.

Same rule for terminology. Pick one noun per concept and never swap it. We say platform account, customer workspace, Station, and print job, and we do not say print request for the persisted object, because two names for one thing is how an agent generates a field that does not exist.

Rule 3: spell out every enum value, in one place, with what it proves

Enums are what agents get wrong most, because a partial list in prose reads exactly like a complete one.

List every value in one table on one page, and for anything that represents an outcome, say what it does and does not prove. Ours:

Status	What it means
pending	Saved and validated, not yet delivered
dispatching	Leased by one server so it is never sent twice
sent	Delivered to the Station
printing	The operating system print system accepted it
completed	The print command succeeded through the OS print path, which is not proof paper emerged
failed	With a reason
canceled	By you, before it was sent
expired	Not dispatched by its deadline
unknown	Interrupted with an unconfirmed outcome

The completed row is the one that matters. An agent that reads "completed: success" will generate code that treats a printed label as confirmed. An agent that reads the row above generates code that checks. The statuses post exists because that distinction needed a whole page.

We do not pass this rule ourselves yet. The status field in our API reference lists seven values in the field table and then describes expired and unknown in prose further down the page, so anything that lifts the table gets an incomplete enum with no sign that it is incomplete. That is the exact failure this rule is about, and it is on the list to fix. The nine-row table above is the complete set.

Rule 4: examples must run exactly as pasted

An agent will paste your example into a file and run it. So every placeholder must be obviously a placeholder, every required header must be present, and nothing may depend on setup described three sections earlier.

The failure to hunt for is the install or setup line that does not work. Our Node client is documented in the monorepo, and its package name does not currently resolve on the public registry, so we print no install command for it anywhere. Saying "the Node client, see the SDK docs" is less convenient than a copy-paste line, and far more convenient than an install command that fails three times in an agent loop before the developer gives up.

Prefer curl for the canonical example. It has no dependency resolution and no version drift, and every agent can translate it into the language at hand.

Rule 5: errors belong in a table with a recovery action

One page, every status code, the cause, and what the caller should do. The recovery column is the part agents actually need, because generated code either handles an error correctly or swallows it.

Code	Cause	What the caller should do
409	Same idempotency key, different content	Do not retry. The business document changed, so use a new key
429	Per-key rate limit	Wait for the interval in Retry-After
413	Payload over the content limit	Reduce the payload rather than retrying

Three rows of that shape prevent more bad generated code than a page of narrative about best practices.

Rule 6: state your limits, because an agent that invents a feature files a bug against you

If you do not say what you lack, an agent will assume the industry-standard feature exists and generate code for it.

Ours, which the docs state and this post repeats: webhooks are not shipped. You ask us for job status, by polling or with the Node client's waitFor helper. Without that sentence on the page, every agent asked to integrate us writes a webhook handler, because every other API in the category has one. The sentence is not modesty, it is a correctness measure.

The same logic drove the blind-spots section of our reliability page, which lists what we cannot see: paper and ribbon running out, a dirty printhead producing a barcode that will not scan, and whether the label reached the right box. Documented limits are what make a page safe to cite, and pages contradicted by reality stop getting cited.

Rule 7: date the page and say what changed

Put a visible date on anything time-sensitive and keep a changelog with real entries. An agent has no way to tell a 2019 page from a current one unless you tell it, and neither does a reader arriving from a search result.

Rule 8: keep marketing out of reference pages

A reference page has one job. Guides and landing pages can have a voice; the page that lists your enum values should read like a specification.

Bad:

Our powerful print engine is designed to give your team complete confidence in every job, with industry-leading reliability and an experience your customers will love.

Good:

POST /v1/print-jobs creates a print job. It returns 201 with the created job, or 200 with the original job and an Idempotency-Replayed header if this is an idempotent replay. Required fields are printerId, contentType, and content.

The second version contains four facts an agent can use. The first contains zero, and it costs context budget to skip.

We are not clean on this one. Our reliability page still opens with a line about someone unplugging the label printer to charge a phone, which is a voice choice on a page that is otherwise reference material. We kept it because humans read that page first, which is a defensible trade and still a trade.

Rule 9: leave robots.txt open to the crawlers you want to be cited by

If you block AI crawlers, you are not in the answer. That is the whole rule, and it is a business decision rather than a technical one.

Our robots.txt allows all agents everywhere except /app/ and /admin/, which are the authenticated console and have nothing to retrieve. We will revisit if crawl cost becomes a real number, and we would rather pay the bandwidth.

Where this connects to agent tooling

If you are writing tools for agents rather than docs, Anthropic's guidance on writing effective tools for AI agents is the better reference, and the two disciplines share a principle: a tool description should say when not to use the tool, exactly as a docs page should say what a feature does not do. The Model Context Protocol, introduced by Anthropic in November 2024 with governance moved to the Linux Foundation in December 2025, is the transport that usually carries it. We do not offer an MCP server, so a printing tool is something a reader builds over our REST API.

What we have done, and what we have not

Done: an OpenAPI 3.1 description of the API, one canonical product description used verbatim, one noun per concept, a reliability page that lists the failures we cannot see, a robots.txt that stays open, and a rule in our content strategy, written this month, that every post links to two other posts and one docs page so a crawler landing anywhere can reach the reference set.

Not done: the complete status enum in one table on the reference page, as described under rule 3. llms.txt, which we are adding. Webhooks, which changes what we document rather than how. And a dry-run endpoint, which is the gap in our own API design checklist.

If you want the vendor-facing version of these questions, the evaluation checklist is the list we would want someone to hold us to.