Skip to main content

Versioning and deprecation policy

Versioning​

The major version is in the path: today /api/v1. Within a major version we only make compatible changes; anything that breaks an existing client needs a new version (/api/v2).

Compatible changes (no prior notice)​

  • New endpoints, optional parameters and scopes.
  • New fields in JSON responses and in webhook data.
  • New webhook events.
  • New error codes for situations that did not exist before.
  • Behaviour fixes that align the API with what is documented.

Write your client to ignore unknown fields and not to depend on property order.

Incompatible changes (with notice)​

  • Removing or renaming an endpoint, field, parameter, scope or event.
  • Changing a field's type or meaning.
  • Making a previously optional parameter required.
  • Changing the webhook signature scheme.

Deprecation​

  1. Announcement. The item is marked deprecated in the changelog with its removal date. Responses from affected endpoints include the Deprecation and Sunset headers where technically possible.
  2. Minimum 12 months' notice between announcement and removal. The feature keeps working unchanged during that period.
  3. Removal. After the date the endpoint may respond 410 Gone.

Exception: a security vulnerability may force a shorter period. It would still be communicated through the changelog and to account administrators.

Webhook signatures​

The signature carries a version prefix (v1=). If the scheme changes, it will be announced with the same 12-month notice and both schemes will coexist for that time. Always check the prefix before validating.