API Versioning
The API uses URL path versioning. Current version:
v1
at /api/v1/.
Versioning Strategy
URL Path
Version in URL path (/api/v1/, /api/v2/)
Response Meta
Every response includes meta.version
OpenAPI Spec
Full spec at /api/v1/openapi.json
or /api/v1/openapi.yaml
Deprecation Policy
Breaking changes result in a new version. Deprecated endpoints receive a
90-day
notice via response headers (Sunset) and documentation before removal.
Version Lifecycle
Current version, fully supported
90-day sunset period, still functional
Header includes deprecation date
Returns 410 Gone
Backward Compatibility
Minor changes (new fields, new endpoints) are backward-compatible and do not trigger a version bump. Always ignore unknown fields in responses.
Migration Guide
When a new major version is released, we provide a detailed migration guide. Common changes include:
- •New required fields in request bodies
- •Renamed endpoints or parameters
- •Changed response shapes
- •Removed deprecated fields