API Documentation: What Good Docs Include (With Examples)

API documentation is everything a developer needs to call your API correctly the first time: how to get access, a reference entry for every endpoint, working examples, every error and what to do about it, and a changelog of what changed. Good API docs have two layers. Guides get someone from nothing to a first successful call and through common tasks. Reference describes every endpoint, field and error completely, ideally generated from an OpenAPI description so it cannot drift from the code. And in 2026 there is a third reader to write for: the AI coding agent that fetches your docs before it writes the integration.

Docs in general, from READMEs to runbooks, are covered in technical documentation. This page is only about APIs.

Reference vs guides

The two layers answer different questions, and mixing them is the most common reason API docs are hard to use. Diátaxis↗ (opens in a new tab) describes reference as “technical descriptions of the machinery and how to operate it,” whose only purpose is “to describe, as succinctly as possible, and in an orderly way.” Guides are the opposite: they pick one goal and walk toward it.

• Quickstart: from sign-up to one successful call in under ten minutes. One language, one endpoint, copy-and-paste commands.
• Authentication guide: how to get a key or a token, where to send it, how long it lasts, and how to rotate it.
• Task guides: one per common job, such as “create an order and take payment” or “sync customers every night.”
• Reference: every endpoint, parameter, field, status code and error, in the same layout every time.
• Changelog: what changed, when, and whether it breaks anything.

A small API can live without task guides at first. It cannot live without a quickstart and complete reference.

An API documentation example: one endpoint page

Every reference entry should follow the same template, so a reader who has seen one has seen them all. Here is a complete one for a fictional store API:

GET /v1/orders/{order_id}

Returns one order, with its line items and shipping address.

Auth      Bearer token with the orders:read scope.
Rate      100 requests per minute per token. See Rate limits.

Path parameters
  order_id   string, required   The order's ID, e.g. ord_8Kx2

Query parameters
  expand     string, optional   "customer" to include the customer
                                object instead of only its ID.

Example request
  curl https://api.example.com/v1/orders/ord_8Kx2 \
    -H "Authorization: Bearer $STORE_TOKEN"

Example response  200 OK
  {
    "id": "ord_8Kx2",
    "status": "paid",
    "currency": "usd",
    "total_cents": 4995,
    "customer_id": "cus_31Qa",
    "shipping_address": {
      "line1": "500 Pine St", "city": "Seattle",
      "state": "WA", "zip_code": "98101"
    },
    "created_at": "2026-09-30T17:04:11Z"
  }

Errors
  401  unauthenticated   Token missing or expired. Get a new one.
  403  forbidden         Token lacks orders:read. Add the scope.
  404  not_found         No order with that ID in this account.
  429  rate_limited      Wait for the seconds in Retry-After.

Notice what it does not leave to guesswork: the scope it needs, the type and format of every field, money as integer cents with a currency, a timestamp with a time zone, a request someone can paste into a terminal, and every error with the fix. The example response is a real response with realistic values, not "string" in every field.

OpenAPI: write the description once

Hand-written reference drifts from the code within months. The fix is to describe the API in one machine-readable file and generate the reference from it. The OpenAPI Specification↗ (opens in a new tab) defines “a standard, programming language-agnostic interface description for HTTP APIs” that lets both humans and computers understand a service “without requiring access to source code.” As of October 1, 2026, the latest published version is 3.2.1, dated September 10, 2026.

From one OpenAPI file you get a reference site, client libraries, mock servers, request validation and contract tests. The fields that matter most for docs are the ones teams skip: a description on every operation and parameter, examples on requests and responses, securitySchemes for auth, tags to group operations, and deprecated: true on anything on its way out. Either generate the file from your code or write it first and generate the code from it, but keep one source.

openapi: 3.2.1
info:
  title: Store API
  version: 2.4.0
paths:
  /v1/orders/{order_id}:
    get:
      summary: Get an order
      tags: [Orders]
      security:
        - bearerAuth: [orders:read]
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order.
        '404':
          description: No order with that ID.

Errors people can act on

An error page is where most developers spend most of their time in your docs. List every error each endpoint can return, say what causes it, and say what to do next. Use one error shape everywhere. RFC 9457↗ (opens in a new tab), the IETF standard for problem details, defines one so you do not have to invent your own: a JSON body with type, title, status, detail and instance, plus any fields you add. It replaced RFC 7807.

The best error bodies name the fix. fenbs does this on its MCP server: when an AI assistant tries something its role does not allow, the refusal names the permission it lacked and the role it holds, in a sentence, so the assistant can tell you what is missing instead of retrying. The format is on the MCP docs page.

Authentication docs

Most failed first calls are auth problems, so the auth guide deserves more care than its length suggests. Say which scheme you use (API key, bearer token, OAuth 2.0), exactly which header carries it, how a developer gets one in the dashboard, which scopes exist and what each allows, how long tokens last and how to refresh them, and how to revoke a leaked key. Show the header with a placeholder such as $STORE_TOKEN, never a real-looking secret, and tell people never to commit keys to a repository.

Changelogs, versions and deprecation

• Keep a changelog for the API, newest first, with dates and versions. The format is in how to write a changelog.
• Version so a number tells people whether to worry. What counts as a breaking change, and how MAJOR.MINOR.PATCH signals it, is in semantic versioning.
• Announce removals before they happen. RFC 9745↗ (opens in a new tab), published in March 2025, defines a Deprecation HTTP response header that tells clients a resource “will be or has been deprecated,” and RFC 8594 defines a Sunset header for the date it stops working.
• Mark deprecated operations and fields in the OpenAPI file, so the reference shows it automatically.

API docs for AI agents

Coding agents now read your docs before your users do: they fetch the reference to get a call right. Two cheap things help them. First, an llms.txt file. The llms.txt proposal↗ (opens in a new tab) by Jeremy Howard, now in a second version modified August 10, 2026, describes a Markdown file at /llms.txt, or at a subpath such as /docs/llms.txt, with an H1 naming the project (the only required part), a short blockquote summary, and H2 sections listing links to the pages an agent should read. It is a proposal, not a formal standard.

Second, a clean Markdown version of each docs page, at the same URL with .md added, which the same proposal recommends. Then link your OpenAPI file from llms.txt, because an agent reads a spec more reliably than prose. Keep examples complete and current: an agent copies them more faithfully than any human does.

# Store API

> REST API for orders, customers and payments. JSON over HTTPS,
> bearer tokens with scopes. Current version 2.4.0.

## Start here
- [Quickstart](https://example.com/docs/quickstart.md): first call in ten minutes
- [Authentication](https://example.com/docs/auth.md): tokens, scopes, rotation

## Reference
- [OpenAPI description](https://example.com/openapi.yaml): every endpoint
- [Errors](https://example.com/docs/errors.md): every error and its fix

## Optional
- [Changelog](https://example.com/docs/changelog.md)

How to write API documentation: a checklist

1. Write the quickstart first, and have someone who has never seen the API follow it while you watch.
2. Put the OpenAPI file in the repository and generate the reference from it in CI.
3. Give every operation a description, every field a type and example, and every endpoint its errors.
4. Run every example in the docs as a test, so a broken sample fails the build.
5. Update docs in the same pull request as the code, and make that part of your definition of done.
6. Add the change to the changelog, and mark anything deprecated with a date.
7. Publish llms.txt and Markdown versions of the pages.

Tracking docs work on fenbs

fenbs is not a documentation tool; it has no pages or wiki. It is where docs work gets tracked next to the code work. A wrong example is a bug, a missing guide is an enhancement, and each gets a ref such as BUG-112 to quote in the pull request, a priority from 1 to 10, and a test status with test notes saying how the fix was checked. “Docs change in the same pull request as the code” is a rule for the Decisions and rules page, which every connected AI assistant reads first. fenbs follows its own advice on agent docs: its product guide and its /llms.txt file are generated from one source.