# Template: API documentation

**Information type:** [Reference](https://docs.redaction-technique.org/en/toolkit/information-types/)

> **Tip: Template**
>
> This is a **starting point to copy and adapt**, not a worked example. It's a specialized instance of the [reference article template](https://docs.redaction-technique.org/en/toolkit/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](https://docs.redaction-technique.org/en/toolkit/information-types/#information-typing-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.

````markdown
## 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.

---

Source: https://docs.redaction-technique.org/en/toolkit/api-documentation-template/