Template: API documentation

Information type:Reference•"What are the details?"

Structured lookup data, exact syntax, parameters, and constraints

Template

This is a starting point to copy and adapt, not a worked example. It’s a specialized instance of the reference article template, shaped for one API endpoint per page. For details on how reference documentation relates to OpenAPI specs and procedural guides, see Information types and API documentation.

Use one copy of this template per endpoint (or per closely related group of endpoints, such as GET/POST on the same resource). Don’t try to document an entire API on a single page - it stops being scannable past a handful of endpoints.

---
title: "<HTTP method> <path>"
description: "<One sentence: what this endpoint does>"
contentType: reference
---

## Overview

<One or two sentences: what this endpoint is for and when to call it.>

## Endpoint

```
<METHOD> <path>
```

## Authentication

<Required auth scheme, or "None" if the endpoint is public.>

## Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `<name>` | path / query / body | `<type>` | Yes/No | <what it does> |

## Request example

```bash
curl -X <METHOD> https://api.example.com/<path> \
  -H "Content-Type: application/json" \
  -d '{ "<field>": "<value>" }'
```

## Response example

```json
{
  "<field>": "<value>"
}
```

## Error codes

| HTTP status | Code | Meaning |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | <when this happens> |
| 404 | `NOT_FOUND` | <when this happens> |

## Related endpoints

- [<Related endpoint>](<link>)

Notes on filling this in

• Every field in the tables must come from the real API contract - the schemaSchemaA formal description of the structure a document or data file must follow: which elements or fields are allowed, in what order, and with which values. Validating content against a schema (DTD, XSD, or RELAX NG for XML; JSON Schema for JSON) catches structural errors before publication.View in glossary →, the validation code, or a live request/response you’ve actually captured. Never invent a plausible-looking parameter or error code; it’s worse than an undocumented one, because a reader will trust and rely on it.
• Keep the request/response examples runnable as written - a reader should be able to paste the curl command and get the shown response (redacting only genuine secrets).
• If the API has a machine-readable contract (such as an OpenAPIOpenAPIA standard, machine-readable format (YAML or JSON) for describing an HTTP API: its endpoints, parameters, request and response schemas, and status codes. Reference documentation can be generated from it, leaving writers to add the usage guidance the description can't carry.View in glossary → specification or JSON Schema), generate from or link directly to it rather than manually duplicating every field it already defines - manual tables and machine contracts will drift apart otherwise. Author manual MarkdownMarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary → reference pages where you need curated guidance, nuanced edge cases, or domain-specific usage context.
• For a working example of documentation published alongside its machine-readable contract, see this manual’s own API: its /schema.json describes every endpoint, and the reference page adds the usage guidance the schema can’t carry.