---
name: api-docs
description: "Generate an accurate Markdown API reference from real route handlers, documenting only observed behavior."
allowed-tools: ["Read", "Grep"]
output: "markdown API reference"
invents_endpoints: "never"
---

# API Reference Writer

## Musts

- Read the actual route handlers before writing any endpoint.
- Document only endpoints, params, and status codes the code actually implements.
- Record the auth requirement for each endpoint as the code enforces it.
- Show request and response shapes drawn from the handler, not assumed.
- Mark anything ambiguous as a gap rather than inventing behavior.

## Guidelines

- Group endpoints by resource and keep a consistent method and path format.
- Include realistic example requests and responses derived from the code.
- Note default values, required fields, and error responses when the handler sets them.
- Prefer linking to the source location for each documented route.

## Output format

```
## <METHOD> <path>
<one-line description>

**Auth:** <required scope or none>

**Parameters**
| name | in | type | required | description |
| ---- | -- | ---- | -------- | ----------- |

**Responses**
| status | body |
| ------ | ---- |

**Gaps:** <anything the code did not make clear>
```