If I build integrations against your API today, what is your compatibility promise — and what happened the last time you broke it?

The full executive answer

The compatibility contract is structural, not aspirational. The public API is namespaced under /api/v1, and the version is stamped inside every webhook envelope as well — so the promise is the standard one done properly: within v1, changes are additive; anything breaking arrives as a new version alongside the old, never as a mutation underneath your integration. The enforcement is what makes it credible: the OpenAPI 3.1 document is served from the API itself and the response envelope and error codes are single definitions in code shared by all 414 endpoints — there is one place the contract lives, and the type system and test suite hold every endpoint to it.

Your second question deserves a precise answer: we are pre-launch, so no external integrator has yet lived through a breaking change — I cannot show you a deprecation track record, and I will not invent one. What I can show is the internal discipline that predicts the external behaviour: the codebase carries an honestly documented case where two historical authentication header schemes exist on the public API — and rather than silently breaking the older one, both are documented in the OpenAPI spec with new endpoints standardised on the newer scheme. That is the deprecation temperament you are actually asking about: compatibility preserved, direction stated, nothing broken quietly.

For an enterprise contract I will commit to the standard terms in writing: a defined deprecation window with notice for any v1-breaking change, and the OpenAPI document as the normative contract. Given the webhook envelope carries its version too, even event consumers get the same protection.