# Poste API versioning & deprecation policy

- The API is versioned in the URL path: `/v1/...`. Within v1, changes are additive only (new fields, new endpoints). Existing fields and endpoints do not change meaning or disappear.
- Deprecations are announced at least **90 days** ahead via: a `Deprecation` header and a `Sunset` header (RFC 8594) on affected endpoints, a note in [llms.txt](https://www.poste.sh/llms.txt), and the changelog.
- A new major version (`/v2`) runs alongside `/v1` for the whole deprecation window.
- Machine-checkable: agents can rely on `operationId`s in [openapi.json](https://www.poste.sh/openapi.json) remaining stable within a major version.