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 schema, 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 OpenAPI 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 Markdown reference pages where you need curated guidance, nuanced edge cases, or domain-specific usage context.