---
trigger: always_on
---

# Backend API Rules

## Development Phase (Pre-deployment)
- Breaking changes are allowed without deprecation.
- Route versioning is optional during this phase. You may:
  - Use unversioned routes (e.g., `/api/*`) while iterating, or
  - Use a provisional version like `/api/v0/*`.
- Pydantic (v2) schemas are the source of truth for all request/response payloads.
  - Keep schema examples updated when fields or validation rules change.
- Keep OpenAPI docs at `/docs` current with every API change.
- Document API changes succinctly with each PR and add brief migration notes to `docs/api/` (e.g., `docs/api/CHANGELOG.md`) as needed.

## Post-deployment Policy (Stabilized)
- Adopt versioned routes under `api/v1/*` and beyond.
- No breaking changes to `v1` without deprecation; introduce `v2` (or later) for breaking changes.
- Maintain deprecation notices and migration guidance in `docs/api/`.

## Consistency and Quality
- Schemas define types, validation, and examples; align handler implementations strictly with schemas.
- Ensure error responses are documented (shape and examples) and include correlation IDs in responses/logs if available.
- Keep auto-generated docs (`/docs`) accurate and readable; ensure example payloads are representative and valid.