Guides · Reference

Versioning & deprecation

The API lives under /api/v1. Every response carries X-Chale-Api-Version: <date> — the contract date of the reference documentation.

Additive changes ship under /v1 without notice: new routes, new optional request fields, new response fields, new enum values in responses (parse unknown values defensively). Breaking changes ship as /v2; the /v1 route keeps working for at least 90 days and answers with

Deprecation: true
Sunset: Fri, 01 Jan 2027 00:00:00 GMT
Link: </api/v2/…>; rel="successor-version"

and deprecated: true in the OpenAPI document (/api/docs-json). Nothing is deprecated today.