API documentation guides
Step-by-step guides to writing API documentation developers can follow, and keeping it accurate as the API changes.
Why API docs matter
What API documentation is, and what it does for the people who use your API and for your own team.
What is API documentation? Parts and examples
What API documentation is, the four parts every API's docs have, what one reference entry contains, how docs differ from an OpenAPI spec, and where they live.
7 min readWhy do I need API documentation?
Why API documentation matters: how developers choose and learn APIs, what your own team gets from it, why AI assistants depend on it, and when a spec and a README are enough.
8 min read
Write the docs
What API documentation needs, and how to write each part.
How to write API documentation: a step-by-step guide
The pages every API needs, from the quickstart and authentication to the API reference, errors and changelog, in the order developers read them.
Start here10 min readAPI reference vs guides: what goes in each
An API reference tells developers what they can call. Guides help them turn those calls into working features. Here's how to write both without making readers search twice.
13 min readHow to document API authentication
What an API authentication page needs: where to get a credential, how to send it, scopes, the 401 and 403 responses, test keys and rotation, with examples for API keys, bearer tokens and OAuth 2.0.
8 min readAPI documentation examples worth learning from
Seven API documentation sites worth studying for their requests, quickstarts, sandbox tests, permissions, version policies, and AI-readable pages.
13 min read
Keep them current
The habits and tooling that keep docs in step with every release.
How to keep API documentation up to date
Why API documentation falls behind the API, and the habits that keep the reference, guides, examples and changelog in step with every release.
8 min readWhat is docs-as-code?
Docs-as-code means writing documentation the way you write software: plain text in Git, reviewed in pull requests, checked in CI and published on merge. How it works, the tools, an example and how to start.
7 min readHow to version API documentation
How to publish a reference for each API version, choose the default, mark deprecated versions with a sunset date, write migration guides and keep old versions from competing in search.
8 min read
Publish the docs
Where API documentation lives, and what hosting it gives your readers.
Swagger UI vs hosted API docs: which do you need?
What Swagger UI does well, where it stops, what a hosted API docs site adds, and how to tell which your API needs, or whether to use both.
7 min readBuild vs buy API documentation: how to decide
What building API documentation on open-source tools involves, what a hosted platform takes off your hands, how to compare the cost, and when each one is the right call.
9 min read
Make them readable to AI
Docs that AI assistants, coding agents and browser agents can read and use.
Try it on your own spec
Publish guides and an interactive API reference on your domain, from an OpenAPI spec or a blank page, on the Free plan.