API Versioning & Deprecation Policy

Current state (what exists today)

• One version is served: v1, under the base path /api/v1 (basePath: /api/v1; the OpenAPI info.version reports 1.0.0).
• No v2 exists. There is no alternate version prefix and no parallel version in production.
• No route has been removed or sunset. Every documented endpoint remains live, including its legacy aliases.
• One spec-level deprecation annotation exists: the legacy liveness alias /healthz is marked deprecated: true in the public OpenAPI spec in favour of the canonical /health endpoint (same view, same contract). It is still served and has no Deprecation/Sunset response headers and no removal date.
• No Deprecation or Sunset HTTP response headers are emitted today, on any endpoint, because nothing is scheduled for removal.

In short: the policy below is forward-looking. Nothing described here has fired yet because there is nothing to deprecate beyond the /healthz alias annotation.

Versioning

• The version is expressed in the URL path: /api/v1/.... A breaking change lands under a new major path (e.g. /api/v2/...), never silently inside v1.
• Additive changes within v1 are backward-compatible by policy: adding new fields to a response object, adding new endpoints, and adding new optional query parameters, are permitted without a version bump and without announcement headers.
• Breaking changes (removing/renaming a field, changing a field's type or meaning, removing an endpoint, tightening validation, changing auth/rate-limit semantics) require a new major version. v1 remains available until its deprecation + sunset cycle below has completed.
• The OpenAPI info.version (1.0.0) is a release marker, not the versioning contract; the URL prefix (/api/v1) is the contract consumers pin to.

Deprecation announcement

When an endpoint (or a specific field/parameter) is scheduled for removal, we will, before removing it:

1. Publish an announcement on the developer portal (/developers) and in the API reference (/docs).
2. Begin emitting a Deprecation HTTP response header on the affected endpoint, of the form:

   Deprecation: Tue, 01 Dec 2026 00:00:00 GMT

   Deprecation is an HTTP-date when the endpoint will be removed (the sunset date). If a replacement exists, a Link header with rel="deprecation" (or rel="successor-version") points at it.
3. Begin emitting a Sunset HTTP response header carrying the same removal date in ISO 8601:

   Sunset: 2026-12-01T00:00:00Z

4. Mark the endpoint deprecated: true in the OpenAPI spec, with the removal date and replacement noted in its description.

These headers are the machine-readable commitment: a client can detect a deprecation from the response without reading any changelog.

Support window

• Minimum support window: 90 days from the first announcement (and first Deprecation header) to removal. During that window the endpoint keeps its current behaviour and response shape.
• The removal date is advertised in the Deprecation/Sunset headers from day one, so the window is never shortened silently.
• Emergency exception: if an endpoint becomes a security or legal risk, we may remove it faster and will say so explicitly. This is the only case where the 90-day minimum does not apply, and we will not use it as a routine path.
• After the sunset date, the endpoint is removed; requests to it return an appropriate 404/410 (Gone) rather than a silently changed response.

What developers should do

• Pin to the version prefix (/api/v1/...), not to a bare host path.
• Treat Deprecation and Sunset response headers as actionable: when you see them, migrate before the advertised date.
• Avoid depending on response fields or endpoint behaviours not documented as stable. (The public spec is the reference for what is supported.)