# Versioning and API evolution

> **TL;DR** — The major version is in the path (`/v1`). Inside it, Wandura only **adds**; any change of shape ships as a new **dated version**, and your key stays pinned to the one it was created with. Read responses tolerantly (ignore unknown fields, unknown values = default case, unknown error codes = by status class) and your integration keeps working without code changes. Breaking changes get **12 months** of overlap, or **30 days'** notice during the beta. Dated versions, ready-made links, `GET /config` and deprecation headers are all live.

## How versions work
| Layer | Example | How you choose |
|---|---|---|
| Major version | `/api/delivery/v1/…` | The path you call. |
| Dated version | `2026-10-02` | Your key is pinned to the version current when it was created. Override per request with the `Wandura-Version` header. |

Every response says which dated version produced it in the `Wandura-Version` header, and carries `Wandura-API-Status: beta` while the API is in beta.

## Read responses tolerantly
| You | In return, Wandura |
|---|---|
| **Ignore fields you do not recognise.** Never validate responses against a closed schema. | Never removes, renames or retypes a field inside a dated version. |
| **Treat an unknown value as the generic case** (for `protection`, `status`…). | Announces new values in the changelog before returning them. |
| **Handle an unknown `error_code` by its status class**: `429` wait `Retry-After`; other `4xx` do not retry; `5xx` retry with backoff. | Never changes the code or status of a case that already has one. |

## Changes that are not breaking
They can appear at any time, without notice: a new endpoint; a new optional parameter; a new response field; a new error code or enum value; a higher rate limit.

## Changes that are breaking
Never silent: removing or renaming an endpoint, parameter or field; a new required parameter; changing a field's type or meaning; changing authentication or the scope an endpoint needs; a different error code for an existing case; a lower rate limit. They ship as a new dated version, or a new major version, or during the beta under the [beta rule](https://docs.wandura.ai/developers/concepts/versioning#beta).

## Dated versions
- **Your key is pinned.** It receives the shape it was built against until that version's sunset date. Keys created before dated versions existed use `2026-10-02`.
- **Try a newer version per request** with `Wandura-Version: <date>`. When your code handles it, move your keys over: a **new** key is pinned to the latest version; **rotating** a key keeps its pin.
- **An unknown or retired version** in the header (or as your key's pin) answers `400` `unsupported_version`, with `supported_versions`, `latest_version` and, for a retired pin, `upgrade_to`. This check happens before the key check, and uses the flat format on every endpoint.
- How to move from one version to the next: [Migrating versions](https://docs.wandura.ai/developers/guides/migrating-versions).

### Version history
#### 2026-10-02
The first dated version: the `v1` shapes as of 2 October 2026. Supported; no sunset date.

## Follow links instead of building URLs
Responses carry the URLs you need next, absolute, in `links`:

| Endpoint | Links |
|---|---|
| [List licensed catalog](https://docs.wandura.ai/developers/reference/catalog) | `self`, `next` (`null` on the last page or when not paging), `playback`, `config` |
| [List creatives](https://docs.wandura.ai/developers/reference/creatives-list) | `self`, `next`; and `self` on each creative |
| [List open videos](https://docs.wandura.ai/developers/reference/videos-list) | `self`, `next` |
| [Get configuration](https://docs.wandura.ai/developers/reference/config) | every endpoint, the docs, the changelog feed |

Cursors are opaque: copy them, never decode or build them.

## Read your configuration
[`GET /api/delivery/v1/config`](https://docs.wandura.ai/developers/reference/config) tells your backend, for your key: the limits that apply to you, your playback settings and ticket lifetimes, batch limits, subtitle languages, the API versions (pinned, latest, supported) and every announced deprecation. Read it at start-up or every few hours instead of hard-coding these values.

## Deprecations and sunset dates
When an endpoint or a dated version is going away, Wandura announces it in four places at once:

1. **Response headers**, on every response served by it: `Deprecation: @<unix seconds>` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)), `Sunset: <HTTP date>` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), and `Link: <https://docs.wandura.ai/…>; rel="deprecation"`.
2. The `deprecations` list in `GET /config`.
3. The machine-readable feed `https://docs.wandura.ai/changes.json` (`api_versions`, `deprecations`).
4. The changelog, and an email to the Admin of every organisation that uses the API.

A single deprecated field gets no header; it is listed in the other three places. Log these headers in your monitoring ([Observability](https://docs.wandura.ai/developers/production/observability)). There are no deprecations today.

## Support window
When a new major version (for example `/v2`) is released, Wandura announces it in the changelog and by email to your Admins, keeps the previous version working unchanged for **12 months**, keeps its docs online as an older version, and then retires it: calls return an error naming the version to move to.

## During the beta
A breaking change inside `/v1` is announced at least **30 days** before it takes effect, in the changelog and by email to your Admins. An urgent security fix may take effect at once; it is announced as soon as it is live.

## Where to follow changes
- **Changelog**: in the menu; every page changed, by day.
- **Change history**: each page links to its own history.
- **`changes.json`**: for your monitoring.
- **Send feedback** at the top of any page if a change surprised you.

## Related
- [Migrating versions](https://docs.wandura.ai/developers/guides/migrating-versions)
- [Canonical API behaviour · Versioning](https://docs.wandura.ai/developers/reference/behaviour#versioning)