API Documentation in Markdown: Template & Examples

Useful API documentation lets a developer authenticate, send one request, understand the response, and recover from common errors. Put a tested quick start before the exhaustive endpoint reference.

The api.example.com endpoints and data below are fictional examples. Adapt the API documentation template, then test every command against your real API.

What API docs need to answer

A reader should be able to find:

1. The base URL and supported versions.
2. How authentication works and how credentials are protected.
3. Available endpoints and required inputs.
4. Success response fields and types.
5. Error shapes, status codes, and recovery steps.
6. Pagination, idempotency, rate limits, and webhook behavior where relevant.

A small API may fit in one file. Larger APIs often separate getting started, concepts, endpoint reference, errors, and changelog. Repository docs are convenient for code review; a dedicated docs repository or platform can also work when ownership and release synchronization are explicit.

Write a tested quick start

Show the shortest safe request that proves authentication and connectivity:

export API_TOKEN="replace-with-a-test-token"

curl https://api.example.com/v1/widgets \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Then show a representative fictional response:

{
  "data": [
    {
      "id": "wid_example",
      "name": "Demo widget"
    }
  ]
}

State prerequisites, required scopes, test-versus-production hosts, and expected status code beside the example. Never place a real credential in documentation, screenshots, shell history, or source control.

Endpoint Markdown template

Use a consistent structure so readers know where to look. The outer fence uses four backticks so the nested triple-backtick examples render correctly:

## `POST /v1/widgets`

Create a widget.

### Authentication

Requires a bearer token with the `widgets:write` scope.

### Request

| Header | Required | Description |
| --- | :---: | --- |
| `Authorization` | Yes | `Bearer $API_TOKEN` |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Unique value used to identify a retry |

```json
{
  "name": "Demo widget",
  "enabled": true
}
```

| Field | Type | Required | Description |
| --- | --- | :---: | --- |
| `name` | `string` | Yes | Display name |
| `enabled` | `boolean` | No | Defaults to `true` |

### Response

#### `201 Created`

```json
{
  "id": "wid_example",
  "name": "Demo widget",
  "enabled": true
}
```

### Errors

| Status | Code | Recovery |
| --- | --- | --- |
| `400` | `invalid_request` | Correct the named field and retry |
| `401` | `unauthorized` | Supply a valid token |
| `409` | `name_conflict` | Choose another name |
| `429` | `rate_limited` | Wait for the documented retry interval |

### curl example

```bash
curl https://api.example.com/v1/widgets \
  -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo widget","enabled":true}'
```

The field names, scopes, limits, responses, and errors above are illustrative. Replace them with behavior confirmed by implementation and tests.

Authentication and secrets

Explain the credential type, how a developer obtains a test credential, where it belongs in a request, required scopes, expiration, revocation, and rotation behavior. Keep examples environment-variable based:

const response = await fetch("https://api.example.com/v1/widgets", {
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
    Accept: "application/json",
  },
});

Do not prescribe a universal rotation interval or storage system. Link to the security policy that applies to your service and warn readers not to expose tokens in client-side code.

Describe errors for recovery

HTTP status alone rarely tells a caller what to do. Define a stable machine-readable code, a human-readable message, a request identifier, and field details when applicable:

{
  "error": {
    "code": "invalid_request",
    "message": "The name field is required.",
    "requestId": "req_example",
    "field": "name"
  }
}

Clarify which errors are safe to retry, whether retries require an idempotency key, and how clients should use Retry-After. Avoid promising that a message string will remain stable unless it is part of the contract.

Cover pagination and limits

For list endpoints, document:

• cursor- or offset-based pagination;
• request parameters and defaults;
• response links or cursors;
• ordering guarantees;
• behavior when the underlying collection changes.

If rate limits apply, state the actual unit, window, scope, relevant response headers, 429 behavior, and backoff guidance. Avoid copying fictional quotas into production docs.

Versioning and deprecation

Say where the version appears (URL, header, or media type), which versions are supported, and how users learn about changes. A version table can help:

Publish only notice periods and support promises your organization has approved. Security, privacy, legal, and contractual review may be necessary before documenting an incident, data behavior, or end-of-support commitment.

OpenAPI and Markdown together

OpenAPI can describe operations and schemas; Markdown is often better for tutorials, concepts, and troubleshooting. Common approaches are:

• use OpenAPI as the authoritative operation schema and generate reference pages;
• hand-write task guides that link to generated reference;
• validate examples and the OpenAPI document in CI;
• review generated output because automation does not prevent runtime drift by itself.

For broader structure and style, use the technical writing workflow. For a repository entry point, see the GitHub README guide.

Publication checklist

• Base URLs, versions, and environments are correct.
• Authentication examples use $API_TOKEN, not real secrets.
• Requests run and responses match current behavior.
• Required, nullable, default, and enum values are explicit.
• Relevant errors include a recovery action.
• Pagination, rate limits, retries, and idempotency are covered where applicable.
• Links and language-specific examples are tested.
• API and docs changes share a release process.

Good API documentation is testable product behavior expressed for humans. Keep examples fictional until they are replaced with verified service details, and update the docs whenever the behavior changes.