# API Documentation (OpenAPI)

> Create comprehensive, accurate, developer-friendly API documentation.

## When to Use
- Documenting REST APIs
- "Generate API docs" / "Write OpenAPI spec"
- Developer onboarding documentation

## Approach
1. **Start from the developer's goal** — what are they trying to DO?
2. **Group by use case, not by endpoint** — "Authentication" → "Get a token, Refresh, Revoke"
3. **Every endpoint needs:** method, path, description, parameters, request body, response (200 + errors), example
4. **Show curl first** — curl is the universal API language
5. **Include error responses** — developers spend more time debugging errors than handling success

## Endpoint Documentation Template
```
### Create a Memory
`POST /api/memory/store`

Store a new memory or update an existing one. Deduplicates by name.

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Short identifier |
| content | string | yes | Memory content |
| type | string | no | Category (default: "reference") |
| tags | string | no | Comma-separated tags |
| importance | float | no | 0.0-1.0 (default: 0.5) |

**Example Request:**
curl -X POST http://localhost:8001/api/memory/store \
  -H "Content-Type: application/json" \
  -d '{"name": "user_timezone", "content": "UTC+9:30 Adelaide", "type": "user"}'

**Response (201):**
{"action": "added", "id": 42, "message": "Memory 'user_timezone' stored."}

**Response (200 — duplicate):**
{"action": "none", "id": 42, "message": "Memory already exists with identical content."}

**Errors:**
| Code | Reason |
|------|--------|
| 400 | Missing required field (name or content) |
| 429 | Rate limit exceeded |
```
