API Versioning & Deprecation Policy

The API is currently unversioned in the URL — there is no /v1/ path prefix and no version request header. Every endpoint documented at /docs is the one and only current surface.

The service does track a single semantic version internally (returned as version in GET /health), but it's informational — it identifies which build is deployed, it isn't something you select or pin to in a request.

We're not claiming this will stay true forever — see "Planned: path-based versioning" on the roadmap for what changes when we do introduce a /v2.

Additive, non-breaking changes (new endpoints, new optional fields, new optional query parameters) ship continuously without notice — they can't break a well-behaved client.

Breaking changes (removing/renaming a field, changing a field's type or meaning, removing an endpoint, tightening validation) are announced in advance on the changelog (with an RSS feed you can subscribe to) and by email to each affected organization's admin(s) — the same delivery channel already used for monthly usage reports and webhook-health alerts.

Nothing in this API is deprecated today. When something is: a deprecated endpoint or field remains fully functional for at least 6 months after its replacement ships. During that window, responses from the deprecated endpoint carry a Deprecation HTTP header (and, where a direct replacement exists, a Link header pointing to it) so you can detect the migration programmatically instead of only by reading docs.

We'll never remove a deprecated endpoint earlier than announced, and we'll extend the window rather than shorten it if migration turnout is slow.

If a change here would affect your integration and the timeline doesn't work for you, reach out — this policy describes our default, not a rule we won't bend for a real migration constraint.