API Contract First Design

Design a complete API for: [FEATURE_OR_SERVICE]

**Consumers:** [WHO_CALLS_THIS — e.g., "React SPA, mobile app, third-party integrations"]
**Auth:** [AUTH_METHOD — e.g., "Bearer JWT", "API key", "public"]

For each endpoint, document:

### [METHOD] /api/v1/[path]
- **Description:** one-line purpose
- **Auth:** required / optional / public
- **Request body:**
  ```json
  { "field": "type — description" }
  ```
- **Response (200):**
  ```json
  { "field": "type — description" }
  ```
- **Error responses:** 400, 401, 404, 422 with example bodies
- **Rate limit:** requests per minute

Also provide:
- Pagination strategy (cursor-based) with example
- Error response format (consistent across all endpoints)
- Versioning strategy
- TypeScript types for all request/response shapes
- OpenAPI/Swagger snippet for one representative endpoint

Design principles: use nouns not verbs in URLs, plural resource names, consistent naming, proper HTTP methods and status codes.