​
Versioned base path

The API is versioned in the URL. The current stable version is v2:

​
What counts as a breaking change

These are non-breaking and may ship anytime:
  • Adding a new endpoint, or a new optional request field.
  • Adding a new field to a response.
  • Adding a new enum value (validate via Meta).
These are breaking, and ship only under a new version:
  • Removing or renaming a field or endpoint.
  • Changing a field’s type or a default.
  • Tightening validation on existing input.

​
Staying compatible

  • Ignore unknown response fields rather than failing on them.
  • Do not hard-code enum lists. Read them from Meta.
  • Watch the Changelog for announcements.
When a new major version is introduced, the previous version stays supported for a documented window before any sunset, with a migration guide.