# IRIZ API versioning

**Current version:** `v1`  
**Base path:** `/iriz/v1/`

## Strategy

1. **Preferred:** `GET /iriz/v1/{endpoint}` (example: `/iriz/v1/health`)
2. **Legacy:** `/iriz/{endpoint}` remains available; responses may include `Deprecation: true` and a `Link` successor header.
3. **Catalog:** `GET /iriz/versions`
4. **OpenAPI:** `/iriz/v1/docs/spec.json` (canonical) and `/iriz/docs/spec.json` (includes deprecated legacy paths)

## Worker vs API version

- **API version** (`v1`): URL prefix for HTTP routes.
- **Worker version** (`GET /iriz/v1/version`): deployed bundle semver.

See `docs/API_VERSIONING.md` in the repository for the full policy.