API documentation examples: Stripe, GitHub, Twilio and 6 samples

API documentation tells developers what an API does and how to call it. It has two halves: a reference, with an entry for every endpoint (method, path, parameters, a sample request, a sample response and the errors it can return), and guides, such as a quickstart, authentication and a changelog. Below, three well-known API docs, Stripe's, GitHub's and Twilio's, are described section by section, followed by six original samples of the parts most teams write by hand, each with notes on why it works.

What API documentation includes

Every set of API docs answers the same questions in roughly the same order. A missing page tends to show up as support tickets.

Stripe's API reference

Stripe's reference opens with an introduction before any resource. It says the API is organized around REST, with “predictable resource-oriented URLs”, form-encoded request bodies, JSON responses and standard HTTP response codes. The same page gives the base URL, https://api.stripe.com, and links the official client libraries for Ruby, Python, PHP, Java, Node.js, Go and .NET. It explains that the API key you send decides whether a request runs in live mode or in a sandbox, and readers who log in see the docs with their own test key and data.

Every resource follows one pattern. The Customers section has a sentence on what the object represents, its endpoints named by task (create, update, retrieve, list all, delete and search customers) and the events it emits, such as customer.created. Each endpoint page has a one-line description, a curl request that pins the API version in a Stripe-Version header, the full JSON response, every parameter with its type and whether it is optional, and a Returns paragraph that says what comes back and when the call raises an error.

Errors get their own page: codes in the 2xx range mean success, 4xx a problem with the request, 5xx a problem on Stripe's side, followed by a table of status codes and four error types. The error object carries a doc_url pointing to more information about the error code, and a param field that names the parameter at fault, so an app can show the message next to the right form field.

What to borrow. Task names for endpoints, a complete response instead of an excerpt, and error messages that lead back to the docs.

GitHub's REST API docs

GitHub keeps articles and reference apart. The landing page offers a quickstart, getting started, authentication, an overview of the REST API, API versions, breaking changes, best practices, and an article on the OpenAPI description that GitHub says fully describes the API. The reference is grouped by product area (Actions, Activity, Apps, Billing, Branches and so on), with endpoint groups inside each.

Each endpoint has the same parts. Create an issue shows its method and path, POST /repos/{owner}/{repo}/issues, and a description that starts with who may call it: “Any user with pull access to a repository can create an issue.” It also warns that the endpoint returns 410 Gone when a repository has issues turned off, and that creating content too quickly can trigger secondary rate limits. Four sections follow, each heading repeating the endpoint's name: the fine-grained access tokens that can call it, its parameters (grouped as headers, path parameters and body parameters), its HTTP response status codes, and code samples in cURL, JavaScript and GitHub CLI. The response appears twice, as an example and as a schema, and the sample request sends a dated X-GitHub-Api-Version header.

What to borrow. Permissions before parameters, and a status code list written for this endpoint, 410 Gone included, rather than a generic one.

Twilio's Messages resource

Twilio's reference page for messages opens with one sentence: “A Message resource represents an inbound or outbound message.” Then come the resource's properties, a table of status values, a section on how a long SMS is counted in segments, and one section per action: create, fetch, read multiple, update and delete. Each property is listed with its type, whether it is required, a PII classification and a description.

The create request goes to POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json, so the API version is a date inside the path. Code samples come in Node.js, Python, C#, Java, Go, PHP, Ruby, the twilio-cli and curl, and each is titled with the task it does, such as sending an SMS message, with variants for SMS, RCS, WhatsApp and Messaging Services.

What to borrow. A personal-data label on every property answers a security reviewer's first question. Status values belong in a table, because a message moves through them. And samples named after a job are easier to find than samples named after an endpoint.

What to borrow from Stripe, GitHub and Twilio

Each of the three is at its best for a different task. Give each one the job it does best, and copy the feature that makes it work.

All three also name the API version a request uses, each in its own place: Stripe in a Stripe-Version header, GitHub in a dated X-GitHub-Api-Version header and Twilio in a date inside the URL path.

Endpoint reference sample

The six samples below document one invented API, Pressline, which publishes articles to a news site and a newsletter. For the first page a developer reads, the quick start guide template has an API quickstart example, and the technical writing examples include a second reference entry, for an invoicing API. This sample is one reference entry, with the scope it needs and a response that shows how values come back.

curl https://api.pressline.example/v2/drafts \
  -H "Authorization: Bearer $PRESSLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publication_id": "pub_8Kd2",
    "title": "Council approves the harbor budget",
    "publish_at": "2026-11-12T06:00:00-05:00"
  }'

{
  "id": "drf_3Qp9",
  "object": "draft",
  "publication_id": "pub_8Kd2",
  "title": "Council approves the harbor budget",
  "status": "scheduled",
  "publish_at": "2026-11-12T11:00:00Z",
  "author_ids": ["aut_51Lx"],
  "created_at": "2026-11-10T14:22:07Z"
}

Why it works. The description says what happens next (the draft stays private) and which scope the key needs. Every parameter has a type, whether it is required, its limit and its default. The request runs as pasted, with the key in an environment variable instead of the page. And the response shows publish_at converted to UTC, which answers the time zone question before anyone files it as a bug.

Authentication section sample

Why it works. One header, shown exactly. The key's prefix tells a developer which workspace a request will touch, and the test workspace promises it can't email real subscribers. Scopes are listed with the advice to use as few as possible, and the section says what to do after a leak, which is the moment people actually read it. Separating 401 from 403 tells the developer whether to fix the key or its permissions.

Error reference sample

{
  "error": {
    "status": 422,
    "code": "publish_at_in_past",
    "message": "publish_at must be in the future. You sent 2026-11-09T06:00:00-05:00.",
    "param": "publish_at",
    "request_id": "req_7Hc1",
    "doc_url": "https://docs.pressline.example/errors#publish_at_in_past"
  }
}

Why it works. Codes are stable strings a program can branch on, while the message is for people and repeats the value that was wrong. The param field names the input at fault, the request_id lets support find the call in seconds, and the doc_url leads back to this table, the same idea as the doc_url in Stripe's error object. The What to do column is what turns a list of codes into help.

Pagination and rate limits sample

GET /v2/drafts?publication_id=pub_8Kd2&limit=2

{
  "data": [
    { "id": "drf_3Qp9", "title": "Council approves the harbor budget" },
    { "id": "drf_3Qn4", "title": "Ferry timetable changes in December" }
  ],
  "next_cursor": "c_9Fk2"
}

Why it works. It states the default, the maximum and the sort order, then says exactly how to recognize the last page, which is the question every loop needs answered. The limits are given per key and per workspace, so a team running several integrations can plan for both. This is the reference version; a concept page that explains how a limit behaves under bursts is a separate document, and the technical writing examples include one.

Webhook event reference sample

{
  "id": "evt_5Rt8",
  "type": "draft.published",
  "created_at": "2026-11-12T11:00:02Z",
  "data": {
    "object": {
      "id": "art_7Lm2",
      "object": "article",
      "draft_id": "drf_3Qp9",
      "url": "https://harborherald.example/council-approves-harbor-budget"
    }
  }
}

Why it works. It says when the event fires and when it doesn't, which is where webhook bugs come from. Security, timeouts, retries and duplicates each get one sentence, and the payload shows the object the developer will actually receive.

OpenAPI description sample

The OpenAPI Specification “defines a standard, programming language-agnostic interface description for HTTP APIs”, written in JSON or YAML. It grew out of the Swagger 2.0 specification, which SmartBear Software donated in 2015, and the OpenAPI Initiative, a Linux Foundation project, now maintains it. Documentation tools such as Swagger UI render the file as interactive reference pages. Here is the Create a draft entry again, as it would sit in the file. The excerpt uses OpenAPI 3.1; the latest published version, as of November 2026, is 3.2.1.

openapi: 3.1.0
info:
  title: Pressline API
  version: "2026-11-01"
servers:
  - url: https://api.pressline.example/v2
paths:
  /drafts:
    post:
      operationId: createDraft
      summary: Create a draft
      description: >
        Creates a draft article in a publication. The draft stays
        private until you publish it, or until publish_at if you set it.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DraftCreate"
      responses:
        "201":
          description: The draft was created.
        "422":
          description: publish_at is in the past.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    DraftCreate:
      type: object
      required: [publication_id, title]
      properties:
        publication_id:
          type: string
          examples: [pub_8Kd2]
        title:
          type: string
          maxLength: 200
          description: Shown as the headline.
        publish_at:
          type: string
          format: date-time
          description: When set, the draft is scheduled for this time.

Why it works. The reference text lives next to the contract, so a renamed field changes in one place. The summary becomes the page title, the description is written by a person, and limits such as maxLength appear wherever the file is shown. What the file can't hold is the rest of the docs: the quickstart, the authentication guide and the reasons behind each design choice. Teams that keep the file and those guides in one repository, reviewed like code, are practicing docs as code.

If you write the guides in Strokes, attach the OpenAPI file to a chat with the Strokes Assistant and ask which parameters, defaults or limits the hand-written pages get wrong.

Habits of good API docs

• Samples that run as pasted. Test keys, realistic IDs, environment variables for secrets, and a full response to compare against. Run every sample before each release.
• One name for each thing. The parameter in the table, the sample and the SDK must match. A short style guide settles naming, capitalization and how code appears in text; the style guide examples include Google's developer documentation guide.
• Versions you can see. Say which version each page describes and keep a dated changelog; the changelog examples include an API changelog with deprecations.
• The unhappy path. Errors, limits, timeouts and retries are where integrations fail, and where docs often stop short.