Catalog

TL;DR — GET /catalog lists every film and episode your organisation may stream right now, with display order, free-episode rule and a readiness flag per episode. Metadata only, never a video URL. Fetch it whole, or in pages with limit and cursor. It is the only film list your app needs; a ticket request re-checks everything anyway.

What is in the catalog#

A film is listed when, at the moment of the request:

• your organisation holds a streaming licence for it, and the licence is active;
• today (UTC) is inside the licence window — whole days, first and last day included;
• the film is published.

For those films it lists every published episode, plus a placeholder row for each planned episode not yet published. Films still in production and review cuts never appear and cannot be played through the API. An empty response ("films": []) means no licence is active for your organisation right now.

Response shape#

Two flat arrays, films and episodes; join them on episodes[].film_id = films[].id. The response also carries links (self, next, playback, config). Every field: List licensed catalog.

Pages#

Without limit or cursor you receive the whole catalog in one response. With limit (1–200 films) you receive one page of films with all their episodes, plus next_cursor and links.next; pass the cursor back unchanged until it is null. Pages are not one consistent snapshot: the rules for syncing safely are in Canonical API behaviour · Pagination, and the code in Catalog sync.

Order#

films arrives sorted by display_order, smallest first, and across pages too. Render films in that order; Wandura edits it, so keep no ordering table of your own. episodes arrives grouped by film, then by episode_no; take the film order from films.

Free and paid episodes#

Episodes with episode_no ≤ the film's free_until_episode are free; the rest are paid. 0 means no free episode; null means none is set, so treat every episode as paid. The value differs per film and can change: read it on every sync.

Planned episodes#

planned_episodes is the number of episodes the film will have. For each one not yet published, the catalog includes a placeholder row so you can show "coming soon":

Never send a placeholder to POST /playback: it has no ID. When planned_episodes is null, there are no placeholders.

Readiness: stream_ready#

true means a ticket can be issued for the episode now. Grey out or hide episodes where it is false. It is a snapshot of the moment you fetched the catalog: the ticket request checks again, and its answer is the one that counts. A not_ready answer for an episode that was stream_ready: true is normal, for example right after a withdrawal.

Genre facets#

Films also carry genres (free-text labels) and language (free text: display it, do not parse it).

Text and artwork#

• synopsis_short for cards, synopsis_full for detail pages; lengths vary, clamp them. Either can be null.
• poster_url (film) can be null while artwork is prepared: show a placeholder.
• For episodes use poster_url (a loadable https URL or null, then fall back to the film poster). poster_uri is an internal reference, not a loadable URL.

Each film also carries images, its artwork by kind, each entry { "kind", "url", "width", "height" }:

A kind Wandura does not have is left out, so the array can be empty; it never holds a null entry. Every url is an absolute https URL on a Wandura host that you can load directly. New kinds may be added: skip a kind you do not know. poster_url stays as it is.

Freshness#

A change on Wandura's side (a publication, a withdrawal, a licence that starts or ends) appears in the catalog within 30 seconds. All bounds: Canonical API behaviour · Freshness. Sync every 15–60 minutes from your server; never call the catalog on app launch.

Related#

• Catalog sync
• List licensed catalog
• When rights end