Public APIs
All posts

API Documentation Examples: 6 Worth Copying

Quick answer: The best API documentation examples to copy are Frankfurter, AbuseIPDB and the Dog API. Each puts the whole surface on one page, makes every example a request you can run immediately, and documents its errors properly. Frankfurter is the single best model, because it also states plainly what it deliberately does not do.

Most articles on this topic show you Stripe, Twilio and GitHub. Those are fine, and they are also the docs of companies with a documentation team, which is not the situation you are in.

So this list is drawn from somewhere else. We run a public API directory, and of the 1,576 live APIs we list, 430 (27.3%) point their canonical URL straight at a documentation surface: a docs. subdomain, a /docs path, a developer. portal. We link-check all of them weekly. That gives us 430 real documentation sites, built mostly by small teams, that we can rank by what they actually do rather than by brand.

What makes API documentation worth copying?

Five things, in the order they matter:

  1. A runnable first example. Not a description of a request. The request, with a real URL, that returns real data when pasted into a terminal.
  2. The errors, catalogued. Every status code you can emit, with the body that accompanies it. This is the most commonly skipped section and the most read one.
  3. Rate limits stated as headers. Names and values, not prose about being reasonable.
  4. An honest scope statement. What the API does not do, said out loud.
  5. A machine-readable copy. An OpenAPI spec, and increasingly an llms.txt, because a growing share of your readers are agents.

The best API documentation examples in 2026, ranked

1. Frankfurter

Verdict: the best model on this list, and the smallest. The Frankfurter docs fit on one page. Every example is a bare curl against api.frankfurter.dev with no key, so you can verify the whole API in about a minute. It has an error table (400, 404, 422) with the JSON body shown, a rate-limit answer in the FAQ that says there are no quotas, and it publishes both an llms.txt and an MCP server for agent readers.

The detail worth stealing is the Conversion section, which exists only to say there is no conversion endpoint, then shows the five lines of JavaScript that do the job. Documenting an absence is rare, and it is the single fastest way to stop a support ticket. One caveat we found while checking: the project moved from frankfurter.app to frankfurter.dev, and the redirect works, but the v1 and v2 docs now live at different addresses.

2. AbuseIPDB

Verdict: the best error and testing documentation we index. AbuseIPDB does three things almost nobody does. It publishes test IP addresses that trigger specific failures, so reporting 127.0.0.2 returns a real 429 with the real body and you can build your retry logic against it before you ever hit a live limit. It documents the rate-limit headers by name with sample values (Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). And its errors conform to the JSON:API spec rather than to a house format invented that afternoon.

It also explains why it sends no CORS headers, which matches the cors: no we record for it: the keys are meant to stay server-side, and allowing browser calls would encourage people to leak them. The flaw: the Python samples are Python 2 (print json.dumps(...) with no parentheses), a language that reached end of life in January 2020.

3. Dog API

Verdict: the clearest quickstart, and proof that a hobby API can out-document a funded one. The Dog API reference opens with a four-row table: base URL, auth, return format, licence. The auth row reads "None. No key, no sign up, just send the request." It then shows the same call as a terminal command and as browser fetch, followed by the actual response body rather than a schema, and links its OpenAPI spec at /api-docs/v2/swagger.json. It serves an llms.txt too.

The weakness is a v1 and v2 split that is easy to land on the wrong side of, and ad slots inside the reference itself, which the maintainer explains funds the free tier.

4. Resend

Verdict: the best example of documentation written for agents as well as people. Resend puts a documentation index at /docs/llms.txt and announces it in the first line of the page, above the human navigation. Every page carries a "Copy page" control, and there is an MCP server alongside the SDKs. This is what docs look like once someone accepts that much of the traffic is machine-read. The trade-off is heavy client-side rendering, so the page reads poorly without JavaScript.

5. IPinfo

Verdict: best library-first structure. IPinfo leads with official client libraries for a dozen languages before showing a single raw request, which is the right order for an API most people consume through an SDK. It documents three authentication methods, ships an OpenAPI spec and an MCP server, and keeps a changelog. The gap is small but telling: it advertises an "OpenAPI Spec & LLM" section, yet ipinfo.io/llms.txt returns 404.

6. Shopify

Verdict: the reference for versioning and change communication at scale. The part of Shopify worth copying is not the endpoint reference. It is the single "About Shopify APIs" page that covers authentication, versioning and rate limits once, for every API, plus a changelog treated as a first-class navigation item. If you version your API, this is how you tell people. Shopify serves no llms.txt, a surprising omission at its size.

What our link-check data says about API documentation

Here is the finding we did not expect. We sweep every listed URL for reachability, and documentation URLs rot faster than the APIs behind them.

Of the 430 documentation surfaces we list, 27 (6.3%) are unreachable right now, against 4.6% across all 1,576 public API entries. The failure mix is 11 hard 404s, 6 DNS failures, 6 403s, 2 503s, a timeout and a connection error.

The 404s are the interesting group, because they are not dead companies. They are live businesses that reorganised their docs and broke the URL: Kraken's docs.kraken.com/rest/, Alchemy's docs.alchemy.com/alchemy/, Sendinblue's developer portal, CircleCI's v1 reference, Klarna's payments API pages, Singapore's data.gov.sg/developer. Every one was a canonical, widely linked address.

So add a sixth rule to the five above: when you move your documentation, redirect the old paths. The best-written reference in the world scores zero from a 404.

One more measurable trend. We checked ten of the documentation sites in this article for an llms.txt file, and seven serve one, including the two smallest projects on the list. The three that do not are among the largest organisations we checked. Agent-readable documentation is no longer a big-company feature; right now it is the opposite.

What should you actually copy?

Copy Frankfurter's shape, AbuseIPDB's error and testing sections, and the Dog API's four-row header. That combination costs a day and beats most vendor documentation we index.

To test any of it against real endpoints, Development and Test Data list APIs that answer without a key. Our measurements of what public APIs really do are in REST API best practices and API authentication methods.

FAQ

What should API documentation include?

At minimum: a runnable example with a real URL, an authentication section that states the method and where the credential goes, a complete error catalogue with response bodies, rate limits named as headers, and a machine-readable spec. Everything else is presentation.

What is the best example of API documentation?

For a small or mid-sized API, Frankfurter, because it proves the whole thing fits on one page. For error handling specifically, AbuseIPDB, because it ships test inputs that let you reproduce each failure deliberately. Stripe is the usual answer and it is a good one, but it is not a model most teams can staff.

Should API documentation include an llms.txt file?

Increasingly yes. Seven of the ten documentation sites we checked for this article serve one, and it costs almost nothing: a plain text index of your documentation pages at /llms.txt. It makes your docs cheaper for coding agents to read correctly, which is now a meaningful share of the people integrating your API.

Why do so many API documentation links break?

Because documentation gets reorganised more often than APIs get rewritten. In our weekly sweep, 6.3% of documentation URLs are unreachable against 4.6% of all entries, and most failures are 404s from live companies that moved their docs without redirects.