Versioning

All endpoints live under /api/v1. Within v1, changes are additive: new endpoints, new optional fields, new optional headers, and new values in lists such as diagnostic codes. Anything that would break a working client (removing or renaming a field, changing a type, making a field required, changing what a status means) goes into a new version, /api/v2, which would run alongside v1.

What your client should do

• Ignore response fields you don't know.
• Treat unknown enum values and diagnostic codes as the general case (for example, a generic validation failure).
• Send Idempotency-Key on writes (Idempotency).
• Watch for the Deprecation: true response header. Sunset gives the earliest removal date, and Link: <…>; rel="successor-version" points to the replacement.

Deprecations

A deprecated endpoint is marked in the reference and announced in the changelog at least 90 days before it is removed (unless a security fix can't wait).