5. Versioning & migrations

5.1 How is the API versioned, and what’s the policy for breaking changes?

/v3 is the current API version. Schema changes and deprecations are announced in advance on the Changelog and by email; see there for what's changed.

5.2 Is there a migration path between versions?

We avoid breaking changes by evolving the schema (adding fields vs removing). Deprecated fields remain available for a transition period and are documented. If a breaking change is unavoidable, it will be announced ahead of time and included in the Changelog.