The API is versioned in the path: /api/v1.
Non-breaking (may ship anytime): new endpoints; new optional request fields; new response fields; new values in response enums; relaxed validation. Write tolerant parsers — ignore fields you don’t know.
Breaking (forces a version): removing or renaming fields or endpoints; changing a field’s type or meaning; changing success status codes; tightening validation on existing fields.
During beta, a breaking change may exceptionally ship on v1 with at least 14 days’ notice by email and changelog. After general availability, breaking changes only ship as /api/v2, with v1 running in parallel for at least 6 months.
