# API Guidelines

- Base path: `/api/v1`
- JSON request and response bodies
- Resource identifiers are opaque strings
- ISO 8601 UTC timestamps at boundaries
- Locale and timezone are explicit request context
- Cursor pagination for high-volume feeds; page pagination where users need page counts
- Filter and sort fields are allow-listed
- Mutations support idempotency keys where duplicate execution is costly

## Response envelope

```json
{
  "data": {},
  "meta": { "requestId": "..." }
}
```

Validation errors use a stable machine code, localized user-safe message, and field errors. Authorization must not leak cross-tenant existence. Controllers delegate to application commands and queries.

## Taxonomy endpoints

`taxonomy-types`, `taxonomy-nodes`, `taxonomy-relationships`, `content-mappings`, `mapping-suggestions`, `evidence`, `capabilities`, `capability-snapshots`, `skill-expectations`, `skill-gaps`, and `content-coverage` live under `/api/v1` and are policy protected.