Versioning and deprecation

This is Akteora's promise about change, written down before there was anyone to break.

The version is in the path

Every route is under /v1. Webhook payloads carry "api_version": "v1". The @akteora/sdk package's major version matches: 1.x is the client for /v1.

What can change without notice

Additive changes ship whenever they are ready, within v1, and are listed in the changelog:

a new route, or a new method on a route;
a new optional request field or query parameter;
a new field in a response or a webhook payload;
a new webhook event type, error type, scope or enum value;
a response header;
wording of title, detail and other text meant for people.

Write clients that allow for these: ignore fields you do not know, handle an enum value or event type you have not seen (treat it as "something else", never crash on it), and branch on type, not on text. Everything generated from the OpenAPI document does this already.

What cannot

A breaking change — removing or renaming a field or route, changing a field's type or meaning, making an optional field required, tightening validation so that a request that worked is refused, changing the shape of a webhook payload — ships only as a new version path, /v2, alongside /v1. Webhook endpoints opt into a new payload version; they are never switched over.

Security fixes are the one exception: if a route must change to stop an abuse, it will, and the changelog will say so.

Deprecation

When something in v1 is to go away — a route, a field, all of v1 once v2 exists:

Six months' notice at least, from the day it is announced to the day it stops working.
It is announced in the changelog, and by email to the owners of every organisation that used it in the previous 90 days.
Every response from a deprecated route says so, with the standard headers:
```
Deprecation: @1788220800
Sunset: Wed, 31 Mar 2027 00:00:00 GMT
Link: <https://docs.akteora.com/changelog#2026-10-01>; rel="deprecation"
```
Deprecation (RFC 9745) is when it was deprecated; Sunset (RFC 8594) is when it stops working. Log them, and alert on them, and nothing will surprise you.
The OpenAPI document marks it deprecated: true until it is removed.
After the sunset, the route answers 410 Gone for a further three months, with a detail that points to its replacement, before it is removed.

Nothing in v1 is deprecated today.