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`.
- 1 Oct 2026 · +3 −3 lines
Show changes
⋯ 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. - ### Why can't I create a key with the `playback` scope? + ### Can I create a key with the `playback` scope myself? - Playback keys can stream your licensed films, so only Wandura issues them. You can create keys with `metadata:read`, `creatives:export` and `webhooks:manage` yourself. See [Authentication](../authentication.md#scopes). + 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). ### I lost a key. Can Wandura show it to me again? ⋯ ### Does rotating a key cause downtime? - Yes: the old key stops working immediately. For a smooth switch, create a second key, deploy it, then revoke the old one. For a playback key, Wandura does this for you: it creates a new playback key, you deploy it, and then Wandura revokes the old one. + 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. ### Is there a sandbox? ⋯
- 1 Oct 2026 · +7 −3 lines
Show changes
⋯ ### Does rotating a key cause downtime? - Yes: the old key stops working immediately. For a smooth switch, create a second key, deploy it, then revoke the old one. + Yes: the old key stops working immediately. For a smooth switch, create a second key, deploy it, then revoke the old one. For a playback key, Wandura does this for you: it creates a new playback key, you deploy it, and then Wandura revokes the old one. + ### Is there a sandbox? + + 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). + ## Catalog ⋯ ### Can I play episodes with a standard HLS player? - No. A standard player loads the playlist and then stalls. Use the Player SDK that Wandura licenses to you during onboarding. + 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). ### Can I cache playback tickets? ⋯ ### Do prefetch requests count as plays? - Not when you send `"intent": "prefetch"`. Without `intent`, every successful ticket request counts as a play. Prefetch requests still count toward your rate limit. + 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. ### Where do subtitles come from? ⋯
- 1 Oct 2026 · +2 −2 lines
Show changes
⋯ ### A film I licensed is missing from the catalog. Why? - 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 your Wandura partner contact. + 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. ### Why do some episodes have `"id": null`? ⋯ ### Does the creatives feed include video files? - No. Records describe each creative but never include a media URL. Ask your Wandura partner contact how final files reach your systems. + No. Records describe each creative but never include a media URL. Ask Wandura how final files reach your systems. ### How do I find out a creative was withdrawn? ⋯
- 29 Sept 2026 · Page created