Documenting for AI: Writing Docs That LLMs Can Navigate

"The AI told me to use an endpoint that does not exist."

We heard this from a developer who was using an AI coding assistant to integrate our API. The assistant had confidently generated code calling `/flights/availability`, which sounds plausible but was never an endpoint we offered. The actual endpoint is `/flights/search`. The AI fabricated the endpoint name because our documentation did not give it enough structured information to recommend the correct one.

This is the new reality of API documentation. Your docs are not just read by human developers. They are consumed by AI assistants, coding tools, and autonomous agents that retrieve information from your documentation and present it (or misrepresent it) to developers. The quality of your docs directly determines whether AI tools give correct or fabricated answers about your API.

Structured sections enable reliable retrieval

AI retrieval systems work by chunking your documentation into segments and matching those segments against developer queries. The structure of your docs determines how well those chunks align with the information developers need.

Consistent heading hierarchies help. When every endpoint page follows the same structure -- Description, Authentication, Parameters, Request Example, Response Example, Errors -- the retrieval system learns to associate headings with information types. A query about "flight search parameters" matches the Parameters section of the flight search page reliably.

Inconsistent structure breaks retrieval. If some pages put parameters before examples and others put examples first, the retrieval system cannot rely on positional cues. If some pages use "Arguments" and others use "Parameters" for the same concept, the system fragments related information across different labels.

We enforce structural consistency through templates. Every endpoint page is generated from the same template skeleton. The sections always appear in the same order with the same headings. This is good for human readers too, but it is essential for AI retrieval.

Embedding schemas inline

One of the most common AI fabrication patterns is inventing parameter names or types. The AI knows the general pattern of how APIs work, so it generates plausible-looking parameter names that happen to be wrong.

The fix is embedding JSON Schema definitions directly in the documentation, inline with the endpoint description. Not behind a link. Not in a separate schema reference file. Inline, right next to the parameter table, where the retrieval system will find it alongside the endpoint description.

When the schema is inline, the AI retrieval system pulls the actual parameter names, types, and constraints directly from the source. It does not have to guess that the parameter is called `departureDate` when it could also be `departure_date` or `departDate` or `date_depart`. The schema tells it exactly.

We include both the human-readable parameter table and the machine-readable JSON Schema on every endpoint page. They are redundant for human readers, but the redundancy serves two audiences without compromising either.

Example completeness prevents fabrication

Incomplete examples are a fabrication trigger. When your documentation shows a request but not a response, the AI fills in the response from its training data, which might be wrong. When your example shows the happy path but not error cases, the AI invents error responses.

Every example in our docs includes the complete request (headers, body, parameters) and the complete response (status code, headers, body). For endpoints with multiple response types (success, various errors), we include examples for each.

This gives AI retrieval systems concrete, correct data to present rather than patterns to extrapolate from. A developer asking their AI assistant "what does the flight search response look like?" gets our actual response structure, not an approximation.

We also include explicit negative examples where relevant. "This endpoint does NOT accept a `returnDate` parameter. For round-trip searches, make two separate search calls." This kind of explicit negation is hard for AI systems to infer but easy to retrieve when stated directly.

Semantic headings vs. generic headings

"Flight Search" as a heading is generic. Multiple pages might match a query that retrieves against "flight search." But "Search for flights by origin and destination" as a heading is semantic -- it describes what the endpoint does in terms that map to how developers phrase questions.

We write headings that match developer questions. Not "Parameters" but "Flight search parameters." Not "Errors" but "Flight search error codes." Not "Examples" but "Flight search request and response examples."

This sounds redundant and verbose for human readers. It is. But the redundancy costs human readers nothing (they skip headings they do not need) and helps AI retrieval significantly (the heading itself contains enough context to match queries accurately).

Page titles follow the same principle. "POST /flights/search -- Search available flights" is both a technical reference (method + path) and a semantic description (what it does). Either half can match a query.

Disambiguation for similar endpoints

When two endpoints could match a developer's query, documentation needs to help the retrieval system distinguish between them.

Our flight search and hotel search endpoints are structurally similar. Both accept location, date, and guest parameters. A query like "search for availability" could match either one.

We add disambiguation sections to each page. The flight search page includes a note: "Looking for hotel availability? See Hotel Search." The hotel search page mirrors this. These cross-references serve human readers who landed on the wrong page, and they serve AI systems by providing explicit signals about which endpoint is which.

We also add "Not to be confused with" sections for endpoints that developers commonly mix up. The booking creation endpoint and the booking intent endpoint serve different purposes. Explicit disambiguation prevents the AI from recommending one when the developer needs the other.

Testing AI retrieval quality

We maintain a test suite of 50+ common developer questions and evaluate how well AI assistants answer them using our documentation.

Questions like "How do I search for flights?" and "What parameters does the booking endpoint accept?" and "What does error code OFFER_EXPIRED mean?" Each question has an expected correct answer sourced from our documentation.

We run these tests periodically against popular AI coding assistants. When an assistant gives a wrong answer, we trace the problem to the documentation. Was the information missing? Was it in a section that did not get retrieved? Was the heading too generic to match the query?

This testing has led to specific documentation improvements. Adding a "Common questions" section to high-traffic pages improved retrieval accuracy for those pages. Embedding the OpenAPI schema directly in endpoint pages reduced parameter fabrication. Adding explicit "this endpoint does NOT do X" statements reduced confusion between similar endpoints.

Writing for AI audiences is not separate work from writing for human audiences. Structured sections, complete examples, and clear headings help both. The techniques that make your docs navigable for an AI system -- consistency, completeness, explicitness -- are the same techniques that make docs useful for humans. You are not choosing between audiences. You are writing documentation that works for everyone.

Nowah is an AI travel agent that searches and books real flights and hotels through conversation — no filters, no thirty open tabs. Plan your next trip.