Deprecation policy

How and when the API changes — and how long you have.

Published as part of the API contract. Takes effect at GA — during the pre-GA testing phase (1.0.0-rc*) the surface may still change with ordinary review.

1. /v1 is additive-only. New endpoints, request/response fields, enum-like string values, and webhook event types may appear at any time. Build tolerant readers: ignore unknown fields and unknown event types.
2. Nothing is removed or changed incompatibly inside /v1. Renames, type changes, removed fields, tightened validation on existing inputs — none of these happen in /v1. (Fixing a response that never worked is not a breaking change.)
3. Deprecation is announced, marked, and slow. When something is scheduled for removal (in a future major version):
   • a changelog entry announces it with the sunset date,
   • affected responses carry Deprecation: @<epoch> and Sunset: <http-date> headers from the announcement onward,
   • registered client contacts are notified directly,
   • the sunset date is at least 12 months after the announcement.
4. Major versions coexist. If a /v2 ever ships, /v1 keeps working through the published sunset window; migration guides land in the portal.
5. Enforcement is mechanical. Every spec change passes an oasdiff breaking-change gate in CI; overriding it requires an architecture decision record and a changelog entry — there is no quiet path to a breaking change.
6. Out of contract: undocumented behavior, error detail strings (use the error code), field ordering, and the exact pacing of rate limits. Problem type URIs, error codes, and documented headers ARE contract.