Most "best API docs" lists rank the same five teams. That's because the bar is high and the names are stable: when one of these teams ships a redesign, the rest of the industry tracks it. This post is a short tour through what each one does well, with concrete details you can lift into your own docs.
Stripe
docs.stripe.com is the canonical reference for "how API docs should feel." The specific moves worth copying:
- Three-column layout with the reference text in the middle and the request/response examples permanently visible on the right. The user never loses the example while reading.
- Language picker in the top right that swaps every example on the page at once — curl, Node, Python, Ruby, PHP, Go, .NET, Java.
- Idempotency, retries, and versioning documented as first-class concepts, not buried in an FAQ.
- A real changelog with version-by-version migration notes.
The lesson is layout: examples are not "below the description." They are next to it.
Twilio
Twilio's docs are the textbook example of building products from the docs. The specific moves:
- Quickstarts per product, each landing on a runnable snippet that you can copy to a terminal and have working in two minutes.
- Tutorials are real applications, not toy ones — building a click-to-call widget end-to-end.
- Edge cases are inline. "What happens if the SMS fails to deliver?" is in the same page as the send method.
The lesson is depth: a single page is allowed to be long if it answers every question a developer has about that one thing.
Linear
Linear's API docs are a masterclass in less is more. The specific moves:
- GraphQL-native docs that don't pretend to be REST. The query examples are real GraphQL queries, not request/response pairs that hide the GraphQL underneath.
- Authentication is one page, not five. OAuth, API keys, webhooks — covered with the minimum surface.
- Webhooks have their own visual treatment with a clear "what your endpoint should look like" template.
The lesson is restraint: if your API is small enough, your docs should be small enough.
GitHub
GitHub's REST API docs carry the most surface area of any public API and still feel navigable. The specific moves:
- Stable URL structure that survives 20+ years of API evolution.
docs.github.com/rest/repos/reposreliably means the same thing even after redesigns. - Versioning is visible. Every page says which API version it documents, with a switcher.
- Each operation has a "Try it" panel with a real auth dance, not a fake placeholder.
The lesson is permanence: design URL structures that survive product changes, because external sites will link to them.
Plaid
Plaid's docs are the answer to "how do you document a financial API?" The specific moves:
- Concept guides separate from reference. "What is Auth?" and "POST /auth/get" are different pages with different jobs.
- Sandbox vs production is explicit on every relevant page, with the data that's safe to use in sandbox listed inline.
- Webhook events have a state diagram, not just a list. The lifecycle of a Plaid link token is a visual.
The lesson is concept docs: reference alone is not enough for an API that has invariants the developer needs to learn first.
Anthropic
The Claude / Anthropic API docs are newer but have set a high bar quickly. The specific moves:
- Cookbooks that aren't "Hello World." They are real recipes for real problems (tool use, multi-turn agents, retrieval-augmented patterns).
- Migration guides between model versions that include parameter changes, behavior changes, and price changes.
- Streaming and SSE documented inline, not as an afterthought.
The lesson is recipes: the gap between "I read the docs" and "I shipped a thing" is bridged by cookbook content that solves real problems end-to-end.
What these six have in common
- The reference page and the example are on the screen at the same time.
- Auth has its own first-class section, not a paragraph at the top.
- Versioning is visible and the migration story is told.
- A changelog exists and is updated when the API changes.
- Webhooks (where applicable) have their own treatment, not a section under "advanced topics."
- The URL structure is stable enough that external links survive product changes.
If your docs site has 4+ of these, you are in great shape. If it has 0–2, the best API documentation tools comparison on the Bloom site has the matrix of which tools make each one easy to ship.
How Bloom helps you ship docs that hit the bar
Bloom Docs emits a reference site from your OpenAPI spec with examples-next-to-reference, a stable URL structure, llms.txt for agent-readable docs, and the rest of the SEO chrome. You bring the cookbook-level content; Bloom takes care of the boilerplate. Start free for 30 days — no credit card required.