# Get configuration

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](https://docs.wandura.ai/v1/developers/concepts/versioning#config).

```
GET /api/delivery/v1/config
```

**Scope:** any valid API key

## Request parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `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
```bash
curl -s https://www.wandura.ai/api/delivery/v1/config \
  -H "Authorization: Bearer $WANDURA_API_KEY"
```

## Response
`200 OK`. New fields may be added at any time: ignore the ones you do not recognise.

| Field | Type | Description |
|---|---|---|
| `api.status` | string | `beta` while the API is in beta. |
| `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. Empty when there is none. |
| `links` | object | Absolute URLs: `self`, every endpoint, `docs`, `evolution` and `changes` (the machine-readable changelog). |

## Response example
```json
{
  "api": {
    "status": "beta",
    "path_version": "v1",
    "version": "2026-10-02",
    "pinned_version": "2026-10-02",
    "latest_version": "2026-10-02",
    "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."
      }
    ]
  },
  "key": { "scopes": ["metadata:read", "playback"] },
  "rate_limits": {
    "window_seconds": 60,
    "doors": {
      "catalog": { "limit": 3000, "unit": "requests" },
      "playback": { "limit": 10800, "unit": "tickets" },
      "creatives": { "limit": 3000, "unit": "requests" },
      "videos": { "limit": 3000, "unit": "requests" },
      "config": { "limit": 600, "unit": "requests" }
    }
  },
  "playback": {
    "domains": ["playback.example.com"],
    "protection": ["private-encrypted"],
    "grant_ttl_seconds": 1800,
    "manifest_url_ttl_seconds": 900,
    "batch": { "max_episodes": 3, "max_next": 2 }
  },
  "subtitles": { "format": "webvtt", "languages": ["en"] },
  "deprecations": [],
  "links": {
    "self": "https://www.wandura.ai/api/delivery/v1/config",
    "catalog": "https://www.wandura.ai/api/delivery/v1/catalog",
    "playback": "https://www.wandura.ai/api/delivery/v1/playback",
    "creatives": "https://www.wandura.ai/api/delivery/v1/creatives",
    "videos": "https://www.wandura.ai/api/delivery/v1/videos",
    "config": "https://www.wandura.ai/api/delivery/v1/config",
    "docs": "https://docs.wandura.ai/developers/reference/overview",
    "evolution": "https://docs.wandura.ai/developers/concepts/api-evolution",
    "changes": "https://docs.wandura.ai/changes.json"
  }
}
```

## Response headers
| 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`. |
| `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` | 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. |
| `X-RateLimit-Window` | 429 | Window length in seconds. |

## 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` (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](https://docs.wandura.ai/v1/developers/reference/videos-get); all counters are in [Canonical API behaviour](https://docs.wandura.ai/v1/developers/reference/behaviour#rate-limits).

What to do for each: [Errors](https://docs.wandura.ai/v1/developers/concepts/errors).