# Wandura Delivery API

The Wandura Delivery API lets your backend stream the short-drama films your organisation has licensed from Wandura. Your server reads your licensed catalog, asks Wandura for a short-lived playback ticket each time a viewer starts an episode, and hands that ticket to the player on the viewer's device. If your organisation also builds ad creatives on Wandura, the same API gives your marketing systems a feed of approved creatives.

## What the API gives you

| Capability | Endpoint | What you get |
|---|---|---|
| Licensed catalog | `GET /api/delivery/v1/catalog` | Every film and episode you may stream right now, with display order, free-episode rules and a readiness flag per episode. Metadata only, never a video URL. |
| Playback tickets | `POST /api/delivery/v1/playback` | A ticket for one episode, valid for 30 minutes, plus the episode's subtitles. |
| Creatives feed | `GET /api/delivery/v1/creatives` and `GET /api/delivery/v1/creatives/{id}` | A data record for each approved ad creative of your organisation, for syncing into your marketing systems. |

## Base URL

```
https://www.wandura.ai
```

Use `www.wandura.ai`, not the bare `wandura.ai`. The bare domain redirects every request to `www`, and some HTTP clients drop the body or headers of a `POST` when they follow a redirect.

## How it fits together

The API is server-to-server. Your API key lives on your backend; the viewer's device only ever receives a playback ticket for the episode it is about to play.

1. **Catalog.** Your backend calls `GET /catalog` and builds its film list from the response. Do not keep a second film list of your own: two lists drift apart, and the result is titles that appear but will not play.
2. **Playback ticket.** When a viewer taps an episode, the player on the device produces two device values. Your backend sends them, with the episode, to `POST /playback`. Wandura checks your licence for that film at that moment and returns a ticket.
3. **Your player.** The device passes the ticket to the Player SDK, which fetches the encrypted stream and its keys and plays.

This is what one play looks like:

```mermaid
sequenceDiagram
    participant Device as Viewer device (Player SDK)
    participant Backend as Your backend
    participant API as Wandura Delivery API
    participant Stream as Wandura streaming network
    Device->>Device: Viewer taps an episode
    Device->>Backend: Episode + device ID + device public key
    Backend->>API: POST /api/delivery/v1/playback (Bearer API key)
    API->>API: Check key scope and licence for this film
    API-->>Backend: vid, play_auth_token, expires_at, protection, subtitles
    Backend-->>Device: vid, play_auth_token, subtitles
    Device->>Stream: Player SDK loads the encrypted stream and keys
    Stream-->>Device: Video plays
```

The key that decrypts the video is bound to the viewer's device. It never passes through your backend or appears in the API response.

## Creatives feed

If your organisation builds ad creatives with Wandura (for example on partner.wandura.ai), approved creatives appear in the creatives feed. Each record describes the creative: film, episodes and scenes used, format, duration, hook, formula and rights end date. The feed never contains a media URL. See [Creatives](https://docs.wandura.ai/developers/concepts/creatives).

## Next steps

- [Quickstart](https://docs.wandura.ai/developers/quickstart): make your first calls in a few minutes.
- [Authentication](https://docs.wandura.ai/developers/authentication): API keys and scopes.
- [Catalog](https://docs.wandura.ai/developers/concepts/catalog), [Playback](https://docs.wandura.ai/developers/concepts/playback) and [Creatives](https://docs.wandura.ai/developers/concepts/creatives): how each part works.
- [Errors](https://docs.wandura.ai/developers/concepts/errors) and [Rate limits](https://docs.wandura.ai/developers/concepts/rate-limits): what can go wrong and how to handle it.
- [API reference](https://docs.wandura.ai/developers/reference/overview): every endpoint, parameter and field.