On this page
- How versions work
- Read responses tolerantly
- Changes that are not breaking
- Changes that are breaking
- Docs for an earlier version
- Dated versions
- Version history
- Follow links instead of building URLs
- Read your configuration
- Deprecations and sunset dates
- Support window
- During the beta
- Where to follow changes
- Related
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 /configand 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.
Docs for an earlier version
When Wandura publishes a new major documentation version, the previous one is kept, not deleted: read it at /v1/developers/… (Vietnamese at /vi/v1/developers/…), with an "older version" banner at the top of each page. A frozen version is not edited again, except for security fixes. If your integration runs against the older contract, that is still the right documentation for you.
The documentation version is not the number in the API path. The current documentation version is v2 because the integration model changed (your organisation's own space), but the REST endpoints stay at /api/delivery/v1/…. Do not go looking for /api/delivery/v2.
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
400unsupported_version, withsupported_versions,latest_versionand, 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.
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 | self, next (null on the last page or when not paging), playback, config |
| List creatives | self, next; and self on each creative |
| List open videos | self, next |
| Get configuration | 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 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:
- Response headers, on every response served by it:
Deprecation: @<unix seconds>(RFC 9745),Sunset: <HTTP date>(RFC 8594), andLink: <https://docs.wandura.ai/…>; rel="deprecation". - The
deprecationslist inGET /config. - The machine-readable feed
https://docs.wandura.ai/changes.json(api_versions,deprecations). - 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). 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
Updated 5 Oct 2026 · Change history (5)