# API versioning

- **Current:** All REST APIs are under **`/api/v1`** (sync, pull, delete, health, info).
- **When to introduce v2:** When you make **breaking changes** (e.g. remove or rename request/response fields, change semantics, or drop support for old clients).
- **How to add v2:**
  1. Add new controllers or paths under **`/api/v2`** with the new contract.
  2. Keep `/api/v1` working for a documented **deprecation period** (e.g. 6–12 months).
  3. Document in OpenAPI and in response headers, e.g. `X-API-Deprecated: true`, `Sunset: <date>`.
  4. Update clients (Android, iOS, Web) to use v2 before sunset; then remove v1.
- **Non-breaking changes** (new optional fields, new endpoints) do **not** require a new version; keep them in v1.