Public beta

Versioning & deprecation policy

We version the API by URL prefix. Today everything lives under /v1/.

What counts as a breaking change

  • Removing a field from a response.
  • Renaming a field or changing its type.
  • Adding a new required parameter.
  • Changing the meaning of an enum value.
  • Removing or renaming an endpoint.

What is not a breaking change

  • Adding new fields to a response.
  • Adding new optional parameters.
  • Adding new endpoints.
  • Adding new webhook event types.
  • Adding new enum values (always be defensive about parsing them).

Build defensively

Treat unknown fields and unknown enum values as forward-compatible additions, not errors. Switch on what you know; ignore what you do not.

Deprecation timeline

  • Deprecations are announced in the changelog and emailed to active integrators.
  • Endpoints stay alive for at least 12 months after deprecation.
  • Deprecated endpoints respond with a Deprecation and Sunset header well before removal.