# API reference (docs/architecture/api.md)

Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **reference document** for the API surface: a route's shape lives here or in the generated spec, never in a feature doc, which states what the route promises and leaves its shape to this catalog. If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).

Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.

```markdown
---
type: api-reference
description: "{at most 300 characters: what this document settles and where its boundary sits}"
---

# API Reference

## Conventions

- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500

## {Resource group}

| Method | Path | Purpose | Auth | Owning doc |
| ------ | ---- | ------- | ---- | ---------- |
| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
```