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, problem extension fields, and the response headers the spec declares (X-Request-Id, RateLimit-*, Retry-After, Idempotency-Replayed, Deprecation, Sunset) ARE contract.