Versioning

Current version

The current API version is v1, reflected in the base path /api/v1.

---

Compatibility policy

Non-breaking changes (no notice required)

The following changes may be introduced to v1 at any time without a version bump:

• Adding new fields to existing response objects
• Adding new enum values to existing fields
• Adding new optional query parameters
• Adding new endpoints

Write your integration defensively - ignore unknown fields rather than failing on them. Do not treat a response object as a fixed schema.

Breaking changes (new version path)

The following changes will only be introduced under a new versioned path (e.g. /api/v2), with advance notice:

• Removing or renaming existing fields
• Changing the type of an existing field
• Removing or renaming endpoints
• Changing authentication mechanics
• Removing existing query parameters

---

Version lifecycle

When a new major version is released:

• The previous version (e.g. /api/v1) will remain available for a deprecation period with advance notice before sunset.
• Deprecation notices will be communicated to token holders via email and documented here.