Versioning

All endpoints live under https://<host>/api/v1/. The version segment is part of the URL — a breaking change produces a new segment (/api/v2/) rather than altering the meaning of existing endpoints under /v1/.

What counts as breaking:

• Removing or renaming a field, endpoint, or query parameter.
• Changing a field type or a response envelope shape.
• Tightening validation in ways that reject previously accepted requests.
• Changing authentication semantics or scope names.

None of those will happen inside v1. Instead they land in /v2, which will run alongside v1 for a deprecation window so you can migrate at your own pace. Additive changes — new optional fields, new endpoints, new event types — do not require a new version and may appear within v1.

When an endpoint or field is scheduled for removal, responses carry a Deprecation header naming the version in which it goes away. Integrations should treat its presence as a signal to migrate:

Deprecation: v2

Every deprecation is also recorded in the changelog with a description of the replacement, so a Deprecation header is never the only warning you get.

• Pin your integration to /api/v1/ and parse version from the URL — do not hardcode endpoints without the version segment.
• Ignore unknown response fields today so additive changes do not break you tomorrow.
• Watch for the Deprecation header in integration tests, not just production.