Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 2 Oct 2026 · +41 −45 lines
Show changes
# FAQ - Answers to the questions developers ask most often while integrating the Wandura Delivery API. If your question is not here, see [Support](support.md). - - ## Keys and access - - ### Can I call the API from a browser or a mobile app? + Short answers, each with a link to the page that owns the details. Not here? See [Troubleshooting](../production/troubleshooting.md) or [Support](support.md). - No. The API is server-to-server: the endpoints send no CORS headers, and your API key must never ship inside a client. Your app talks to your backend, and your backend talks to Wandura. + ## Keys and access {#keys-and-access} - ### Can I create a key with the `playback` scope myself? + ### Can I call the API from a browser or a mobile app? {#can-i-call-the-api-from-a-browser-or-a-mobile-app} - Yes. Any **Admin** or **Developer** of your organisation creates it on **Developers** by picking **Stream films in an app**. If a playback key leaks, anyone can stream your licensed films, so keep it on your server and revoke it immediately if you think it has leaked. See [Authentication](../authentication.md#scopes). + No. The API is server-to-server: no CORS headers, and a key inside a client can be extracted. Your app talks to your backend. See [Security](../concepts/security.md#trust-boundary). - ### I lost a key. Can Wandura show it to me again? + ### Can I create a key with the `playback` scope myself? {#can-i-create-a-key-with-the-playback-scope-myself} - No. The full key is shown once, when it is created. Rotate it or create a new one on the **Developers** page. + Yes: any Admin or Developer, on **Developers** → **Stream films in an app**. See [Authentication](../authentication.md#scopes). - ### Does rotating a key cause downtime? + ### I lost a key. Can Wandura show it again? {#i-lost-a-key-can-wandura-show-it-to-me-again} - Yes: the old key stops working immediately. For a smooth switch, create a second key, deploy it, then revoke the old one. This works the same for playback keys. + No. It is shown once. Rotate it or create a new one. - ### Is there a sandbox? + ### Does rotating a key cause downtime? {#does-rotating-a-key-cause-downtime} - No. Every environment calls `https://www.wandura.ai`. You test with your own keys, in the organisation Wandura chooses for testing, and test plays are recorded like any other. See [Test and production](../integration-guide.md#test-and-production). + Yes: the old secret stops working within seconds, with no overlap. For no downtime, create a second key, deploy it, then revoke the old one; mind the version pin. See [Security · Key lifecycle](../concepts/security.md#key-lifecycle). - ## Catalog + ### Is there a sandbox? {#is-there-a-sandbox} - ### A film I licensed is missing from the catalog. Why? + No separate host. Tests call production with the keys of your **test organisation**: sample films only, plays not counted, errors simulated on demand. See [Testing](../guides/testing.md). - The catalog lists a film only while your streaming licence for it is active, today is inside the licence window (in UTC), and the film is published. Check the licence dates with Wandura. + ## Catalog {#catalog} - ### Why do some episodes have `"id": null`? + ### Is the catalog paginated? {#is-the-catalog-paginated} - They are placeholders for episodes that are planned but not published yet, so you can show "coming soon" tiles. They always have `"status": "planned"` and `"stream_ready": false`. See [Catalog](../concepts/catalog.md#planned-episodes). + Optionally. Without `limit` you get everything in one response; with `limit` (1–200 films) you page with `cursor`. Pages are not one snapshot: see [Canonical API behaviour · Pagination](../reference/behaviour.md#pagination). - ### The catalog said `stream_ready: true`, but playback returned `not_ready`. Is that a bug? + ### A film I licensed is missing. Why? {#a-film-i-licensed-is-missing-from-the-catalog-why} - No. `stream_ready` is a snapshot taken when you fetched the catalog. Playback checks again on every request, and a title can be withdrawn in between. Show "not available yet" and refresh your catalog. + The licence must be active, today (UTC) inside its window, and the film published. Check the dates with Wandura. See [Catalog](../concepts/catalog.md#what-is-in-the-catalog). - ### How do I know which episodes are free? + ### Why do some episodes have `"id": null`? {#why-do-some-episodes-have-id-null} - Episodes with `episode_no` less than or equal to the film's `free_until_episode` are free. Read it from the catalog; it differs per film. + They are placeholders for planned episodes ("coming soon"). Never send them to playback. See [Catalog](../concepts/catalog.md#planned-episodes). - ## Playback + ### `stream_ready` was `true`, but playback said `not_ready`. A bug? {#the-catalog-said-stream-ready-true-but-playback-returned-not-ready-is-that-a-bug} - ### Why do I get `409 sdk_required`? + No. The catalog is a snapshot; the ticket request checks again. Show "Not available yet" and re-sync. - Licensed episodes are encrypted and can only be played through the Player SDK. Send the device values `union_info` and `drm_kek` from the SDK with your request. See [Playback](../concepts/playback.md#send-the-device-values). + ## Playback {#playback} - ### Why do I get `400 invalid_device_info`? + ### Can I request tickets for several episodes in one call? {#can-i-request-tickets-for-several-episodes-in-one-call} - One of the device values looks empty, for example the literal string `"(null)"`. This usually happens when an SDK call returns nothing and your code converts it to text. The `fields` array tells you which value to fix. + Yes: up to 3 per call, with `episodes` or with an episode plus `next`. Each ticket counts 1 toward your limit. See [Request playback](../reference/playback.md). - ### Can I play episodes with a standard HLS player? + ### Can I cache playback tickets? {#can-i-cache-playback-tickets} - No. A standard player loads the playlist and then stalls. Use the Player SDK: Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. The setup guide is on partner.wandura.ai → **Developers** → **Player SDK**, available after [onboarding](../before-you-start.md#get-onboarded). + Yes, per viewer, **device**, episode and intent, until 5 minutes before `expires_at`. Never across devices: a ticket only decrypts on the device it was issued for. With a stable `viewer_ref`, Wandura does this for you. See [Canonical API behaviour · Reuse](../reference/behaviour.md#ticket-reuse). - ### Can I cache playback tickets? + ### Why do I get `409 sdk_required` or `400 invalid_device_info`? {#why-do-i-get-409-sdk-required} - No. A ticket expires 30 minutes after it is issued. Request one per play start, and request a fresh one if the player fails mid-session. + The device values from the Player SDK are missing (`409`) or look empty, such as `"(null)"` (`400`). See [Playback and tickets](../concepts/playback.md#send-the-device-values). - ### Can I request tickets for several episodes in one call? + ### Can I play episodes with a standard HLS player? {#can-i-play-episodes-with-a-standard-hls-player} - No. Each request covers one episode. If your app preloads the next episode, request its ticket separately and send `"intent": "prefetch"`. + No: it loads the playlist and stalls. Use the Player SDK. See [Player SDK](../player-sdk/index.md). - ### Do prefetch requests count as plays? + ### Do prefetch requests count as plays? {#do-prefetch-requests-count-as-plays} - Not when you send `"intent": "prefetch"`. Without `intent`, or with a value other than `play` or `prefetch`, every successful ticket request counts as a play. Prefetch requests still count toward your rate limit. + Not with `"intent": "prefetch"`. They do count toward your rate limit. Requests without `intent`, or with another value, count as plays. - ### Where do subtitles come from? + ### Where do subtitles come from? {#where-do-subtitles-come-from} - Every playback response includes a `subtitles` array of WebVTT files. An empty array means none are attached yet. See [Playback](../concepts/playback.md#subtitles). + From each ticket, as WebVTT files. See [Subtitles](../guides/subtitles.md). - ## Creatives + ## Creatives {#creatives} - ### Does the creatives feed include video files? + ### Does the feed include video files? {#does-the-creatives-feed-include-video-files} - No. Records describe each creative but never include a media URL. Ask Wandura how final files reach your systems. + No. Records describe each creative; ask Wandura how final files reach you. - ### How do I find out a creative was withdrawn? + ### How do I find out a creative was withdrawn? {#how-do-i-find-out-a-creative-was-withdrawn} - The feed has no deletion events. Call `GET /creatives/{id}`: a creative that is no longer available returns `404` with `code` `4040`. + `GET /creatives/{id}` answers `404` `4040`. There are no deletion events. See [Creatives sync](../guides/creatives-sync.md). - ### Why did the same creative arrive twice? + ### Why did the same creative arrive twice? {#why-did-the-same-creative-arrive-twice} - Incremental syncs can return a record again. Store records keyed by `creative_id` and overwrite them. See [Creatives](../concepts/creatives.md#syncing-incrementally). + Incremental syncs can repeat a record. Overwrite by `creative_id`.
- 2 Oct 2026 · Page created