Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 2 Oct 2026 · +2 −1 lines
Show changes
⋯ | `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. | | `Wandura-Version` | all | The dated API version (YYYY-MM-DD) this response was produced in: the version pinned to your API key, or the one you sent in the `Wandura-Version` request header. Keys created before dated versions existed use `2026-10-02`. | + | `Wandura-Request-Id` | all | An opaque id for this request (`req_` followed by 26 characters). Every response carries it, errors included, and error bodies repeat it as `request_id`. Log it, and quote it when you contact Wandura about a request: it finds the exact request in our logs. Do not parse it. | | `Deprecation` | 200 | Present only when this endpoint, or the dated version serving this response, is deprecated (RFC 9745): `@<unix seconds>` of the deprecation date. Log it in your monitoring. | | `Sunset` | 200 | Present only when a deprecated endpoint or dated version has a date when it stops working (RFC 8594), as an HTTP date. | | `Link` | 200 | Present with `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (and `rel="sunset"`) pointing to the page that explains what to use instead. | - | `Cache-Control` | 200 | Always `no-store`. Do not cache these responses in shared caches. | + | `Cache-Control` | all | Always `no-store`. Do not cache these responses in shared caches. | | `Retry-After` | 429, 503 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. | | `X-RateLimit-Limit` | 429 | Requests (for playback, tickets) allowed per window for this endpoint group and your organisation. | ⋯
- 2 Oct 2026 · +59 −34 lines
Show changes
# Get configuration - Returns the configuration that applies to the calling API key and its organisation: rate limits, playback domains, batch limits, subtitle languages, API versions and deprecations. Read it when your backend starts, or every few hours, instead of hard-coding these values. See [API evolution](../concepts/api-evolution.md#config). + Returns the configuration that applies to the calling key and its organisation: rate limits, playback settings and ticket lifetimes, batch limits, subtitle languages, API versions and deprecations. Read it when your backend starts, or every few hours, instead of hard-coding these values. See [Versioning and API evolution](../concepts/versioning.md#config). ``` ⋯ ``` - **Scope:** none — any valid API key. + **Scope:** any valid API key - ## Request parameters + ## Request parameters {#request-parameters} | Name | In | Type | Required | Description | |---|---|---|---|---| - | `Authorization` | header | string | Yes | `Bearer <API key>`. | - | `Wandura-Version` | header | string | No | A dated version (`YYYY-MM-DD`) to use for this request instead of the version pinned to your key. See [Dated versions](../concepts/api-evolution.md#dated-versions). | + | `Authorization` | header | string | Yes | `Bearer <API key>` for a key with the `any` scope. | + | `Wandura-Version` | header | string | No | Optional. A dated API version (YYYY-MM-DD) to use for this request instead of the version pinned to your API key. Unknown or retired values answer 400 with `error_code` `unsupported_version`. | + | `Wandura-Simulate` | header | string | No | Optional, test organisations only. Asks Wandura to answer with a simulated error so you can test how your app handles it, for example `rate_limited`, `service_unavailable` or `not_entitled:outside_window`. The simulated response has the same status, body and headers as the real one, plus a `Wandura-Simulated` header naming the scenario. It issues no ticket and does not count against your rate limits, except `partial_batch`, whose first item is a real ticket. Simulated responses have their own limit of 300 per minute per organisation. Keys of production organisations ignore this header completely. An unknown value, or a scenario this endpoint does not support, is ignored and the request runs normally. See the Testing guide for the list of scenarios. | - ## Request example + ## Request example {#request-example} ```bash ⋯ ``` - ## Response + ## Response {#response} `200 OK`. New fields may be added at any time: ignore the ones you do not recognise. ⋯ |---|---|---| | `api.status` | string | `beta` while the API is in beta. | - | `api.path_version` | string | The major version in the path, `v1`. | - | `api.version` | string | The dated version this response was produced in (also in the `Wandura-Version` response header). | - | `api.pinned_version` | string | The dated version pinned to the calling key. | - | `api.latest_version` | string | The newest dated version. | - | `api.version_header` | string | `Wandura-Version`. | - | `api.supported_versions[]` | array | Each with `version`, `released_at`, `deprecated_at` (or null), `sunset_at` (or null), `summary`. | - | `key.scopes[]` | array of strings | Scopes of the calling key. | - | `rate_limits.window_seconds` | integer | Length of the counting window, in seconds. | - | `rate_limits.doors.<name>` | object | Per endpoint group (`catalog`, `playback`, `creatives`, `videos`, `config`): `limit` — the ceiling that applies to your organisation per window (null = no ceiling) — and `unit` (`tickets` for playback, where one episode in a batch counts one; `requests` otherwise). See [Rate limits](../concepts/rate-limits.md). | - | `playback.domains[]` | array of strings | Domains your playback URLs use. | - | `playback.protection[]` | array of strings | Protection levels your organisation can receive (see [Playback](../concepts/playback.md)). | - | `playback.grant_ttl_seconds` | integer | Lifetime of a play token. | - | `playback.manifest_url_ttl_seconds` | integer | Lifetime of a signed manifest URL. | - | `playback.batch.max_episodes` | integer | Most episodes one [Request playback](playback.md) call may ask for. | - | `playback.batch.max_next` | integer | Largest `next` value in one call. | + | `api.path_version` | string | Major version in the path, `v1`. | + | `api.version` | string | Dated version this response was produced in. | + | `api.pinned_version` | string | Dated version pinned to the calling key. | + | `api.latest_version` | string | Newest dated version. | + | `api.version_header` | string | Name of the version header, `Wandura-Version`. | + | `api.supported_versions` | array | Dated versions you can use today. | + | `key.scopes` | array of strings | Scopes of the calling key. | + | `key.test_organisation` | boolean | `true` when the calling key belongs to a test organisation (its traffic is not counted as views or usage, and it may send `Wandura-Simulate`). | + | `rate_limits.window_seconds` | integer | Length of the counting window in seconds. | + | `rate_limits.doors` | object | Per endpoint group: `catalog`, `playback`, `creatives`, `videos`, `config`. | + | `playback.domains` | array of strings | Domains your playback URLs use. | + | `playback.protection` | array of strings | Protection levels your organisation can receive. | + | `playback.grant_ttl_seconds` | integer | Lifetime of a play token, in seconds. | + | `playback.manifest_url_ttl_seconds` | integer | Lifetime of a signed manifest URL, in seconds. | + | `playback.batch.max_episodes` | integer | Most episodes one playback call may request. | + | `playback.batch.max_next` | integer | Largest `next` value in one playback call. | | `subtitles.format` | string | `webvtt`. | - | `subtitles.languages[]` | array of strings | Subtitle languages present on films you are licensed to. Updated within 5 minutes. | - | `deprecations[]` | array | Every announced deprecation: `id`, `endpoint`, `field` (null = the whole endpoint), `deprecated_at`, `sunset_at`, `replacement`, `info_url`, `summary`. | + | `subtitles.languages` | array of strings | Subtitle languages present on films you are licensed to (updated within 5 minutes). | + | `deprecations` | array | Every announced deprecation. Empty when there is none. | | `links` | object | Absolute URLs: `self`, every endpoint, `docs`, `evolution` and `changes` (the machine-readable changelog). | - ### Response example + ## Response example {#response-example} ```json ⋯ "version_header": "Wandura-Version", "supported_versions": [ - { "version": "2026-10-02", "released_at": "2026-10-02", "deprecated_at": null, "sunset_at": null, "summary": "First dated version: the /v1 response shapes as of 2 October 2026." } + { + "version": "2026-10-02", + "released_at": "2026-10-02", + "deprecated_at": null, + "sunset_at": null, + "summary": "First dated version: the /v1 response shapes as of 2 October 2026." + } ] }, ⋯ ``` - ## Errors {#errors} + ## Response headers {#response-headers} - Flat format: `{ "error": "…", "error_code": "…" }`. See [Errors](../concepts/errors.md). + | Header | Responses | Description | + |---|---|---| + | `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. | + | `Wandura-Version` | all | The dated API version (YYYY-MM-DD) this response was produced in: the version pinned to your API key, or the one you sent in the `Wandura-Version` request header. Keys created before dated versions existed use `2026-10-02`. | + | `Deprecation` | 200 | Present only when this endpoint, or the dated version serving this response, is deprecated (RFC 9745): `@<unix seconds>` of the deprecation date. Log it in your monitoring. | + | `Sunset` | 200 | Present only when a deprecated endpoint or dated version has a date when it stops working (RFC 8594), as an HTTP date. | + | `Link` | 200 | Present with `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (and `rel="sunset"`) pointing to the page that explains what to use instead. | + | `Cache-Control` | 200 | Always `no-store`. Do not cache these responses in shared caches. | + | `Retry-After` | 429, 503 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. | + | `X-RateLimit-Limit` | 429 | Requests (for playback, tickets) allowed per window for this endpoint group and your organisation. | + | `X-RateLimit-Window` | 429 | Window length in seconds. | - | HTTP | `error_code` | When | + ## Errors {#errors} + + | Status | `error_code` | When | |---|---|---| - | 400 | `unsupported_version` | The `Wandura-Version` header, or the version pinned to your key, is unknown or retired. The body adds `supported_versions` and `latest_version`. | - | 401 | none | Missing, unknown or revoked key. | - | 403 | none | Your organisation is suspended (`error` is `org_suspended`). | - | 429 | `rate_limited` | The `config` ceiling for your organisation is reached. Wait `Retry-After` seconds. | - | 503 | `service_unavailable` | The key could not be checked in time. Retry after `Retry-After` seconds. | + | 400 | `unsupported_version` | The `Wandura-Version` header, or the version pinned to your key, is unknown or retired. The body adds `supported_versions` and `latest_version` (and `upgrade_to` when your pin was retired). | + | 401 | none | The `Authorization: Bearer` header is missing, or the key is unknown or revoked. | + | 403 | none (`error` is `org_suspended`) | Your organisation's access is suspended. | + | 429 | `rate_limited` | The rate limit for the configuration endpoint was reached. | + | 503 | `service_unavailable` | Wandura could not verify the API key in time. The key is not wrong: retry after `Retry-After` seconds, with backoff. | + | 503 | `service_unavailable` | Wandura could not read your configuration in time (`Could not read your configuration in time — retry`). Retry after `Retry-After` seconds, with backoff. | + + `rate_limits.doors` lists every counter except the one of [Get one open video](videos-get.md); all counters are in [Canonical API behaviour](behaviour.md#rate-limits). + + What to do for each: [Errors](../concepts/errors.md).
- 2 Oct 2026 · +1 −1 lines
Show changes
# Get configuration - **Rolling out.** Returns the configuration that applies to the calling API key and its organisation: rate limits, playback domains, batch limits, subtitle languages, API versions and deprecations. Read it when your backend starts, or every few hours, instead of hard-coding these values. See [API evolution](../concepts/api-evolution.md#config). + Returns the configuration that applies to the calling API key and its organisation: rate limits, playback domains, batch limits, subtitle languages, API versions and deprecations. Read it when your backend starts, or every few hours, instead of hard-coding these values. See [API evolution](../concepts/api-evolution.md#config). ``` ⋯
- 2 Oct 2026 · Page created