Versioning & deprecation policy

How the Drazill API is versioned, how changes are announced, and what is deprecated today.

The Drazill API is served under /api/v1. Additive changes — new endpoints, new optional request fields, new response fields — ship in place without a version bump. A breaking change (removing an operation or a documented response, or adding a required request field) goes through an approval recorded in docs/api/breaking-change-approvals/ first, so it is announced with a migration window rather than a surprise.

Deprecation lifecycle

Every route carries a lifecycle: STABLE → BETA → DEPRECATED.

  • STABLE — the default; covered by this policy in full.
  • BETA — usable but non-contractual; the shape may change without a declared breaking change.
  • DEPRECATED — still works, but scheduled for removal. Deprecated operations emit RFC 8594 headers on every response: Deprecation (the deprecation date), Sunset (the date after which the operation may stop working), and Link: <successor>; rel="successor-version". The version that served a request is echoed in Drazill-API-Version.

Sunset window (owner decision — pending). The proposed default a deprecated operation keeps working after its Deprecation date is 90 days, matching the legacy /openapi.json window already in effect. This is the operating default integrators should plan against; it has not yet been ratified as the contractual window, and enterprise agreements may specify a longer one.

Currently deprecated

These endpoints are deprecated and redirect (or point) to a stable successor. They keep working during their window.

EndpointSuccessorSunset
/openapi.json/api/v1/openapi.json2026-08-08

These operations are flagged deprecated in the contract and have no scheduled sunset yet — migrate at your convenience to the keyset successor, which is index-backed and stable under concurrent inserts:

OperationSuccessorSunset
GET /api/v1/notifications/notifications/cursorNo sunset scheduled
GET /api/v1/rank/history/rank/history/cursorNo sunset scheduled
GET /api/v1/wallet/positions/positions/cursorNo sunset scheduled
GET /api/v1/wallet/transactions/transactions/cursorNo sunset scheduled

Subscribe

Every entry in the changelog timeline is dated, and it is available as an RSS feed at https://drazill.docs.buildwithfern.com/changelog/log.rss (Fern serves it by appending .rss to the changelog path). Point your reader at it to be notified of deprecations and breaking changes — including future-dated sunsets — before they land.

The machine sources of truth remain the pinned OpenAPI contract (GET https://api.drazill.com/api/v1/openapi/v1.json) and the webhook event schemas (current version 2026-05-08).