How to write API documentation developers actually use

I can tell within about ninety seconds whether an API's documentation was written by someone who has integrated against an API before. The tell isn't the design or the word count. It's whether the docs answer the questions in the order a developer actually asks them: what does this thing do, how do I authenticate, show me one complete request that works, and what does it look like when it breaks?

Most API documentation fails because it's written in the wrong direction — from the inside out. The team that built the API documents what each endpoint is, parameter by parameter, because that's how they think about it. The developer integrating against it needs to know what the API lets them do, and they need one working example more than they need ten pages of abstract description. This guide is the structure I use, page type by page type, plus the part most guides written before 2024 miss entirely: a growing share of your readers are not human, and the docs have to work for them too.

Start with the five page types every API needs

Before writing a single endpoint description, get the skeleton right. Almost every good API documentation site is built from the same five page types, and almost every bad one is missing at least two of them:

1. A getting started guide. From zero to one successful API call in the fewest possible steps. One path, no branching, ending in a real response the reader can see. This is the single highest-traffic page you will ever write, and its job is momentum, not completeness.
2. An authentication page. Where credentials come from, how they're passed, how they expire, and one copy-pasteable example of an authenticated request. Auth is where most integrations stall, and burying it inside another page is the most common structural mistake I see.
3. Endpoint reference pages. The systematic catalogue — every endpoint, every parameter, every response shape. This is what most people picture when they say "API docs," but it's one page type of five, not the whole site.
4. Guides for real tasks. "Accept a payment." "Sync users." "Handle webhooks." Guides cut across endpoints the way actual work does. Reference answers what is this; guides answer how do I do the thing I came here to do.
5. An errors page. Every error code, what causes it, and what to do about it. Developers land on this page at the worst moment of their integration — frustrated, mid-debug, often from a search engine. A good errors page converts that moment from a support ticket into a fixed bug.

If your docs have a different shape, that's fine — but check it against this list, because gaps here are gaps a reader falls into. Notice also that these map cleanly onto separate concerns: reference is generated-feeling and exhaustive, guides are narrative and opinionated. Mixing the two registers on one page is how documentation gets simultaneously too long and not helpful.

The anatomy of a good endpoint reference page

Reference pages are where consistency matters more than prose quality. Every endpoint page should answer the same questions in the same order, so a reader who has seen one has seen them all:

• What it does, in one sentence. "Creates a new invoice and optionally finalizes it." Plain language, present tense, no marketing.
• The method and path, exactly as sent: POST /v1/invoices.
• Parameters in a table — name, type, required or optional, and a description that says something the name doesn't. customer_id (string, required): The ID of the customer to invoice earns its place. name (string): The name does not.
• One complete request example that works when copy-pasted with real credentials substituted in. Not a fragment, not pseudocode — a full request including the auth header.
• The response, shown in full, with the fields that matter called out. Developers reverse-engineer your data model from response examples far more than from your descriptions.
• The errors this endpoint actually returns, linked to the errors page.

Two writing rules carry most of the weight here. First, examples before abstractions: a developer pattern-matches from one concrete request faster than from any amount of parameter description, so lead with the example and let the table support it. Second, document the defaults and the limits — what happens when an optional parameter is omitted, what the rate limit is, what the maximum page size is. Undocumented defaults are where integrations break silently.

## Create an invoice

Creates a new invoice for a customer. The invoice starts in `draft`
status unless `finalize` is set to `true`.

`POST /v1/invoices`

| Parameter     | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `customer_id` | string  | Yes      | The customer to invoice.                         |
| `finalize`    | boolean | No       | Finalize immediately. Defaults to `false`.       |

That's Markdown, on purpose. Plain, structured source is what keeps your reference portable across tools — and, as we'll get to, it's the format machines read best.

Write the errors page like you'll be debugged against

The errors page deserves its own section because it's the most underwritten page in most API docs and the one with the clearest payoff. Every documented error needs three things:

1. The code and message, verbatim. Developers search for the exact string the API returned. If your docs don't contain that string, the search engine sends them to Stack Overflow instead of to you.
2. What actually causes it. Not "the request was invalid" — which invalidity. "Returned when customer_id references a deleted customer" turns a mystery into a fix.
3. What to do next. Retry with backoff? Re-authenticate? Stop and check a setting? Say so.

This page is also quietly one of your best organic search assets. Error-message queries are high-intent, low-competition, and they bring in developers at the exact moment your product is in front of them. Write it once, properly, and it compounds.

Keep the reference honest

API documentation has a property that makes it harder than other technical writing: it makes precise, testable claims about software that changes weekly. A parameter table that was perfect at launch is a liability two renames later, and stale reference docs are worse than no docs, because they're wrong with confidence.

The structural fix is treating docs as code: reference pages live in the same repository workflow as the API itself, doc updates ride along in the pull requests that change behavior, and a changed endpoint with an unchanged doc page is something a reviewer is allowed to block. The cost of stale API docs also went up recently, for a reason that deserves its own section.

Your API docs now have two audiences — and one of them is an AI agent

The developer integrating your API this week may never load your reference page in a browser. Increasingly, they describe the integration to Claude Code, Cursor, or Windsurf, and the agent writes the request — using either your real, current documentation, or its training-data memory of your API from sometime last year. If the agent can't reach the former, it ships the latter: a plausible-looking call with a renamed parameter or a deprecated auth scheme, and your support queue inherits the result.

Writing for this audience is mostly the same discipline, applied harder. Clean heading hierarchy, one endpoint per section, parameters in real tables, complete request and response examples in fenced code blocks — everything that helps a human skim also helps a model parse and retrieve. On top of that, the AI-readable documentation layer adds machine-facing surface area: an llms.txt index of what exists, per-page Markdown mirrors so agents get clean content instead of HTML soup, and — the strongest version — an MCP server that lets coding agents query your live docs directly while they write the integration. For an API, this is the difference between agents that cite your current reference and agents that hallucinate your endpoints. Your documentation has become the runtime interface to your product; API reference is where that's most literal.

Don't hand-build the scaffolding

Everything above is about content and structure, because that's the part only you can do. The site around it — navigation, search, a reference tab separate from guides, dark mode, the AI layer — is the part you shouldn't be building by hand in 2026.

This is the workflow I'd recommend: write your API docs as the Markdown files described above, one endpoint or topic per file, frontmatter on every page, and run:

npx doccupine

The open-source CLI turns that folder into a complete documentation site — sidebar built from your structure, full-text search, tabbed sections so the API reference lives beside the guides instead of tangled into them, and the whole AI surface (per-page Markdown mirrors, llms.txt, a RAG-powered docs assistant, and an MCP server) included by default. The output is a standard Next.js app you can self-host anywhere, free. When you'd rather not run the hosting, domains, and deploy pipeline yourself, the Doccupine platform takes the same site and manages it for you.

The checklist

The short version, before you ship:

• Five page types: getting started, authentication, endpoint reference, task guides, errors.
• Getting started reaches one real API call with no detours.
• Every reference page: one-sentence summary, method and path, parameter table, full request example, full response, linked errors.
• Defaults, limits, and rate limits documented — especially the ones that only bite in production.
• Errors documented verbatim, with causes and fixes.
• Docs change in the same pull requests as the API.
• Machine-readable layer in place: heading hierarchy, Markdown mirrors, llms.txt, MCP.

If you're staring at an undocumented API and don't know which page to write first, write the getting started guide — and if you get stuck, email [email protected]. Reading half-finished API docs and suggesting the next move is genuinely one of my favorite kinds of email.