History: Get configuration

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