Versioning and deprecation
The major version is in the path: /v1. The description’s own version (info.version in /v1/openapi.json, today 1.0.1) follows the changelog.
What can change within /v1
Section titled “What can change within /v1”Additive changes ship in /v1 at any time, listed in the changelog:
- new operations, and new optional parameters or request fields;
- new response fields;
- new enum values (statuses, kinds, sources);
- new error codes for new situations;
- new scopes.
Write your client to tolerate them: ignore fields you don’t know, and handle an unknown enum value or error code gracefully. Enums in the reference are marked extensible.
Breaking changes
Section titled “Breaking changes”A breaking change ships only in a new major version (/v2). Breaking means removing or renaming a field, operation or scope; changing a type, a default or the status code for the same situation; making an optional input required; or rejecting input that used to be valid. Tradecraft’s build checks every release of the description against the last published one and refuses an unannounced breaking change.
When /v2 is generally available, /v1 keeps working for at least 12 months.
Deprecation
Section titled “Deprecation”Before an operation or field goes away, its responses carry:
| Header | Example |
|---|---|
Deprecation |
@1798761600 — when it was deprecated (RFC 9745) |
Sunset |
Thu, 01 Jul 2027 00:00:00 GMT — when it stops working (RFC 8594) |
Link |
<…>; rel="deprecation" — the docs explaining the replacement |
There are at least six months between Deprecation and Sunset. The changelog announces it, and the admins of organizations whose clients used it in the last 30 days are emailed. After the sunset, the operation answers 410 ENDPOINT_REMOVED, naming its replacement.
Watch for the Deprecation header in your logs. The legacy organization x-api-key (not part of /v1) uses the same headers on a shorter timeline: it stops working 90 days after the API launches — see Moving from x-api-key.