# Versioning and deprecation What changes without notice, what needs a new major version, and how deprecations are announced. The major version is in the path (`/v1`). The contract's `info.version` follows semver; the deployed build version is returned by `GET /health`. ## Non-breaking changes Shipped without notice: new endpoints, new optional request fields, new response fields, new enum values in responses, new problem types and new webhook event types (delivered only when subscribed). Clients must ignore unknown fields and tolerate unknown enum values. ## Breaking changes Removing or renaming fields or endpoints, changing types or semantics, making optional input required, tightening validation, changing defaults and changing auth or scope requirements. Breaking changes ship only in a new major version (`/v2`) and are marked **BREAKING** in the [changelog](/changelog). ## Deprecation A deprecated operation is marked `deprecated: true` in the contract and keeps working until its sunset date. Its responses carry: ```http Deprecation: @1790121600 Sunset: Wed, 31 Mar 2027 00:00:00 GMT Link: ; rel="deprecation" ``` - `Deprecation` (RFC 9745): when the operation was deprecated, as `@`. - `Sunset` (RFC 8594): when it stops working, at least **6 months** after the deprecation for integrator-facing operations. - `Link` with `rel="deprecation"`: the entry on the [deprecations page](/deprecations), with the migration path. Usage of deprecated operations by API keys is reported to the operator. Webhook payloads carry `apiVersion`. ## Contract releases Each contract release is listed in the [changelog](/changelog) with what integrators must do. The published contract is downloadable as [`openapi.json`](/openapi.json) and is also served by every environment at `GET /v1/openapi.json`.