Examples of API Documentation: Stripe, GitHub, Twilio
November 11, 2026 · 11 min read
Examples of API Documentation: What Stripe, GitHub and Twilio Get Right
The strongest examples of API documentation come from Stripe, GitHub and Twilio, plus an OpenAPI sample file of the kind that sits behind many generated references. Between them they get four things right: a first request you can run at once, plain authentication, a full error list and visible versioning. Below, we open each doc and point at the parts worth copying.
What Is API Documentation?
API documentation is the set of pages that tells a developer how to call an API. It covers which endpoints exist, how to authenticate, what requests and responses look like and what each error means. Good docs pair a reference with guides, so readers can look up one field or follow a task from start to finish.
The Diataxis framework splits technical docs into four kinds: tutorials, how-to guides, reference and explanation. API docs need all four. A quick start is a tutorial, "send a webhook" is a how-to, the endpoint list is reference, and a page on idempotency is explanation. Our examples of technical writing include an annotated quick start and a reference entry.
There's also a second layer that readers rarely see. Many teams keep a machine-readable description of the API, usually an OpenAPI file, and generate the reference pages from it. The human page and the file describe the same thing, which is why you'll find both when you search for sample API documentation.
Examples of API Documentation Worth Studying
These four are the ones we send people to first. Each is free to read and shows a different strength.
| Example | Page to open | What it does best |
|---|---|---|
| Stripe API reference | docs.stripe.com/api | A sample test key in every example, a status code summary and all four error types |
| GitHub REST API docs | docs.github.com/en/rest | Exact rate-limit numbers, rate-limit headers and a dated version header |
| Twilio API overview | twilio.com/docs/usage/api | Short pages on requests, responses, conflicts and best practices |
| OpenAPI api-with-examples | learn.openapis.org/examples | The raw file a generator turns into a reference page |
The sections below take them one at a time. Read each with a question in mind: what would a new developer need in the first ten minutes, and where does this page answer it?
Stripe's API Reference: Requests and Responses Side by Side
Stripe's reference opens with the facts every caller needs. It names the base URL, https://api.stripe.com, and says the API takes form-encoded request bodies and returns JSON. It also lists official client libraries for Ruby, Python, PHP, Java, Node.js, Go and .NET.
The authentication section is the part most teams should copy. Stripe puts a sample test key into every example, so you can run any request on the page right away. The curl version looks like this:
curl https://api.stripe.com/v1/charges \
-u sk_test_YOUR_KEY:
The -u flag sends the key as the HTTP Basic Auth username with an empty password. The trailing colon stops curl from asking for one. Test keys start with sk_test_, so the prefix itself tells you which mode you're in.
Then there's the Stripe errors page. It has a status code summary (200, 400, 401, 402, 403, 404, 409, 424, 429 and the 5xx range), each with one line of meaning. Below that, it lists the four error types: api_error, card_error, idempotency_error and invalid_request_error. Finally, it documents every field of the error object, including type, code, message, param and doc_url.
Stripe's versioning is explicit as well. Plain curl requests use your account's default API version unless you send a Stripe-Version header, while newer official libraries pin the version they shipped with. Versions carry a date and a name, such as 2026-10-28.endive, the current one on Stripe's versioning page in November 2026.
GitHub's REST Docs: Authentication, Rate Limits and Versioning
GitHub's REST docs are the clearest example of numbers written down instead of implied. Here's one request that touches auth and versioning at once:
curl -i https://api.github.com/user \
-H "Authorization: Bearer YOUR-TOKEN" \
-H "X-GitHub-Api-Version: 2026-03-10"
It returns the user the token belongs to. The -i flag prints the response headers as well, so you can see the rate-limit counters.
The authentication page says the token goes in the Authorization header after the word Bearer. It adds that token usually works in its place, except for JSON web tokens, which need Bearer.
GitHub's rate-limit page gives exact figures. Unauthenticated requests get 60 an hour per IP address. Authenticated users get 5,000 an hour, and GitHub Apps owned by or installed on a GitHub Enterprise Cloud organization get 15,000.
It also names the headers: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset and x-ratelimit-resource. Go over the limit and you get a 403 or 429, with x-ratelimit-remaining at 0. The page then tells you to wait until the time in x-ratelimit-reset before retrying, which is the kind of next step most error docs leave out.
The GitHub API versions page is short and complete. Requests without the X-GitHub-Api-Version header get 2022-11-28. The page lists each supported version with its end-of-support date, or notes that none is scheduled yet, and a version that's no longer supported returns 410 Gone.
Twilio's API Overview: A Dated URL and Four Short Pages
Twilio takes a different route that's worth comparing. Its core API puts a date in the URL path, https://api.twilio.com/2010-04-01. Requests use HTTP Basic auth, with an API key SID as the username and its secret as the password.
The overview is a good example of API documentation that stays short. Instead of one long page, it links to four focused ones: making requests, working with responses, handling mutations and conflicts, and following best practices. A reader with one question opens one page.
So three APIs give you three versioning styles: a date in the URL path (Twilio), a header with a fixed default (GitHub) and a header with an account default (Stripe). Whichever you pick, document it on one page.
Error Reference Examples: Status Codes and Problem Details
An error reference tells the caller what went wrong and what to do next. The standard shape for that is problem details, defined in RFC 9457, which replaced RFC 7807. Responses use the media type application/problem+json:
{
"type": "https://api.example.com/problems/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "You sent 120 requests in the last minute. The limit is 100.",
"instance": "/v1/orders"
}
The type is a URI that identifies the problem and can point at its doc page. The title is a short summary of the problem type that shouldn't change between occurrences, while detail explains this one. status repeats the HTTP code, and instance is a URI reference for this specific occurrence. You can add your own extension fields, such as a retry time.
Your docs then need a page that lists every type. A plain Markdown table does the job, as the Markdown table guide explains. Edit the one below and watch the preview update:
We prefer docs that list errors twice: a short table next to each endpoint, plus one central page like Stripe's. Readers hit the first while building and search for the second while debugging.
Sample API Documentation as a File: The OpenAPI Description
The OpenAPI Initiative publishes an api-with-examples sample that's the most literal answer to a search for API documentation samples. It's an OpenAPI 3.0.0 file titled "Simple API overview" with two paths. Here's the first one, with its example payloads cut out:
openapi: 3.0.0
info:
title: Simple API overview
version: 2.0.0
paths:
/:
get:
operationId: listVersionsv2
summary: List API versions
responses:
'200':
description: 200 response
'300':
description: 300 response
Rendered as a reference, that becomes one GET / entry headed "List API versions", with the 200 and 300 responses listed under it. The full sample adds a second path, /v2, with 200 and 203 responses and a JSON example for each.
To make OpenAPI documentation for your own API, write the description in YAML by hand or export it from your framework, then validate it against the spec. The current OpenAPI Specification is 3.2.1 as of November 2026. A generator then renders the file into reference pages, though it can't write your guides. Our roundup of API documentation generators compares ten options, and the YAML format cheat sheet covers the syntax if you write it by hand.
What Should API Documentation Include? A Checklist from These Examples
Put the examples side by side and the same seven parts show up. Use this as a checklist for your own docs:
| Part | Why it matters | Who does it well |
|---|---|---|
| Getting started | The first successful call builds trust | Stripe's sample test key |
| Authentication | Every request fails without it | GitHub's header format |
| Endpoint reference | Readers look up one field at a time | Stripe's reference |
| Errors | Callers need a next step | Stripe's error types |
| Rate limits | Clients must plan retries | GitHub's exact numbers |
| Versioning and changelog | Upgrades shouldn't break silently | GitHub's version list |
| Code samples | Copying beats reading | Stripe's per-library samples |
When you sit down to write each endpoint page, the Markdown documentation guide has an endpoint template with a parameters table and request and response blocks.
One limitation to keep in mind: public examples show the finished result, not the process. You won't see how Stripe keeps its samples in sync or who reviews GitHub's version list. Copy the structure, then budget time for maintenance.
Writing Code Samples in API Docs That Readers Can Copy
Code samples are the part readers actually paste. Three habits make them safe to copy. Tag every fenced block with a language, show one complete request rather than fragments, and write placeholders in capitals, like YOUR_TEST_KEY, so readers see what to replace.
Set your key once, then run the request:
```bash
export API_KEY=YOUR_TEST_KEY
curl https://api.example.com/v1/orders -u "$API_KEY:"
```
That renders as a sentence followed by a bash block, which platforms with highlighting colour as shell code. Readers paste their real key once, into the variable, and every later command reuses it.
The Markdown code block guide covers fences and language tags in detail. If you want a block with a diff view or line numbers, the code block generator builds it in your browser. Our editor's preview shows code blocks without colour, so check highlighting on the platform where your docs live.
The best examples of API documentation share one habit: they answer a developer's next question before it's asked. Start with a test key that works, a documented auth header and a full error list, then add versioning before you need it. Draft your error tables and quick start in the editor, where the preview shows the tables as you type, and download the result as a .md file.