Skip to main content

API versioning and deprecation

The full policy is in base URL and versioning.

This page covers the practical stuff: what can change without warning, what needs a new version, and what you need to do in your integration.

Build for additive change​

The major version is in the path (/v1). Within a major version, we can add things without announcing each change. Your integration should be able to handle:

  • new fields in a response
  • new values in an existing enum
  • new webhook event types
  • new error code values within an existing error type
  • new optional request parameters

Two of these cause problems more often than the others.

Unknown enum values. A client that exhaustively switches over a status and throws on the default branch will break when we add a new value. Treat an unknown value as unknown, rather than as an error.

Unknown event types. Your webhook handler should return 200 for an event type it doesn't recognise. A 4xx response causes the delivery to be retried, and enough retries can disable your endpoint.

What gets a new version​

Anything that could break an existing integration gets a new major version.

That includes removing or renaming a field, changing a field's type or meaning, making an optional parameter required, or removing a webhook event type.

These changes won't happen inside /v1.

Deprecation​

When we deprecate an endpoint, it keeps working for a while and starts telling you about it:

Deprecation: true
Sunset: Sat, 31 Jul 2027 23:59:59 GMT

We give 12 months' notice before removing an endpoint or field, and 24 months' notice before a major version reaches end of life.

Security-related removals may happen faster. If that happens, we'll communicate with you directly.

If you only alert on one response header from this API, make it Sunset.

Pinning behaviour​

Aleta-Version lets you pin behavioural defaults to a specific dated release within the major version:

Aleta-Version: 2026-07-28

Additive changes can still reach you. If you leave the header out, you get the current release.

Webhook payloads keep track of their version separately. Each event includes the api_version it was serialized with, so replaying an event from last month gives you the same payload shape it had then.

Last updated on