# API versioning and deprecation policy

- The path segment is the API version: `/api/v1` is current.
- A version is never changed incompatibly in place. Additive changes (new fields, new
  operations, new optional parameters) ship without a version bump.
- When a successor version ships, the old one keeps running alongside it and answers every
  response with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers naming the
  removal date, at least 180 days out.
- Removal is announced in the OpenAPI document (`x-deprecation-policy`) and in the
  storefront's agent guide: https://gonzalezbrothers.coffee/agents.md.

Contract: https://api.gonzalezbrothers.coffee/openapi.json