Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 2 Oct 2026 · +24 −49 lines
Show changes
# Creatives - The creatives feed gives your marketing systems a long-term data record for each ad creative your organisation has approved on Wandura. Each record says what the creative is: the film, the episodes and scenes it uses, its format and duration, its hook, the formula it was built with and when your rights to use the film end. Your systems store these records and decide which creatives to use and how. - - ## What the feed contains - - The feed returns creatives that belong to your organisation and have status `approved` or `pushed` (already delivered). Creatives in any other status, such as drafts, are not included. Creatives of other organisations are never visible. + > **TL;DR** — The creatives feed gives your marketing systems a data record for each ad creative your organisation has approved on Wandura: film, episodes and scenes used, format, duration, hook, formula and the end of your rights. Records never contain a media URL. Sync them incrementally with `updated_since` and a cursor. - A record never contains a media URL. The feed describes the creative; final video files are not delivered through this API. Ask Wandura how final files reach your systems. + ## What the feed contains {#what-the-feed-contains} - `final.ready` tells you whether the final render of the creative exists yet. + Creatives of your organisation with status `approved` or `pushed` (already delivered). Drafts and other organisations' creatives never appear. `final.ready` says whether the final render exists. Final video files are not delivered through this API: ask Wandura how they reach your systems. - ## Endpoints + ## Endpoints {#endpoints} | Endpoint | Use | ⋯ | [`GET /api/delivery/v1/creatives/{id}`](../reference/creatives-get.md) | Fetch or re-check one record. | - Both need a key with the `creatives:export` scope, which you can create yourself on the **Developers** page of the partner portal. See [Authentication](../authentication.md). + Both need a key with `creatives:export` ([Authentication](../authentication.md#scopes)) and share one rate-limit counter. - ## Response envelope + ## Response envelope {#response-envelope} - Unlike the catalog and playback endpoints, the creatives endpoints wrap every response in an envelope: + Successful responses are wrapped in an envelope: ```json ⋯ ``` - `code` is `0` on success and a four-digit error code otherwise. Timestamps in this feed, including `server_time`, are Unix epoch seconds. See [Errors](errors.md). - - ## Syncing incrementally - - Records are returned oldest update first, ordered by `updated_at` and then by ID, so new updates never shift pages you have already read. - - 1. **First sync.** Call `GET /creatives?limit=100` without `updated_since`. While `data.next_cursor` is not `null`, call again with `cursor=<next_cursor>`. - 2. **Save a checkpoint.** Keep the largest `updated_at` you received. - 3. **Later syncs.** Call with `updated_since=<checkpoint>` and page through with `cursor` again. Only records updated strictly after that second (`>`) are returned. - - ```bash - curl -s "https://www.wandura.ai/api/delivery/v1/creatives?updated_since=1790600000&limit=100" \ - -H "Authorization: Bearer $WANDURA_API_KEY" - ``` - - `updated_at` is rounded down to the second, so a record can appear again in the next sync. Store records keyed by `creative_id` and overwrite on repeat. + Errors use the same envelope **without** `data` (`code` is then a four-digit error code), except `429` and `400` `unsupported_version`, which use the flat format. Timestamps in this feed, `server_time` included, are Unix epoch seconds. See [Errors](errors.md#creatives-envelope). - Treat `cursor` values as opaque. Pass them back exactly as received. + ## Syncing {#syncing-incrementally} - ### Creatives that leave the feed + Records come oldest update first (by `updated_at`, then ID), so updates made during a sync land after the pages you have read. Keep a checkpoint (the largest `updated_at` of your last complete run), pass it as `updated_since`, page with `cursor`, and overwrite records by `creative_id`: a record can arrive twice. The full procedure and code: [Creatives sync](../guides/creatives-sync.md). - The feed has no deletion events. If a creative stops being approved, it simply stops appearing. To confirm that a stored creative is still available, call `GET /creatives/{id}`: it returns `404` (`code` `4040`) for a creative that is no longer in the feed. + ### Creatives that leave the feed {#creatives-that-leave-the-feed} - ## The record + There are no deletion events. A creative that is no longer approved stops appearing. To check one you stored, call `GET /creatives/{id}`: `404` with `code` `4040` means it is gone. - The main fields of a record are below. The full list, with types, is in the [list creatives reference](../reference/creatives-list.md#the-creative-record). + ## The record {#the-record} | Field | What it tells you | |---|---| - | `creative_id` | Stable ID of the creative. Use it as your primary key. | - | `creative_code` | Immutable human-readable code of the creative. Treat it as an opaque string. | - | `film` | Film code, title, language and genres. | - | `episodes` | Episode numbers the creative uses. | - | `scenes` | Each clip used: episode number, start and end in milliseconds, action label and spoken line. | - | `hook` | The action label and line of the opening scene. | - | `placement`, `aspect` | Ad placement (`reels_9x16`, `feed_4x5` or `square_1x1`) and its aspect ratio. | + | `creative_id` | Stable ID. Your primary key. | + | `creative_code` | Immutable human-readable code; treat it as opaque. | + | `film`, `episodes`, `scenes` | What the creative is made of: film, episode numbers, each clip with its start, end, action and line. | + | `hook` | The action and line of the opening scene. | + | `placement`, `aspect` | `reels_9x16`, `feed_4x5` or `square_1x1`, and the aspect ratio. | | `duration_ms` | Total length of the clips used. | - | `formula` | The formula the creative was built with, if any. | - | `rights.ends_at` | The last day of your export rights for the film (00:00 UTC of that day), or `null`. | - | `lineage.parent_creative_id` | The creative this one was derived from, if any. | + | `formula` | The formula it was built with, if any. | + | `rights.ends_at` | 00:00 UTC of the **last day** of your export rights, or `null`. That day is included: stop using the creative at `ends_at + 86400`. | | `final.ready` | Whether the final render exists. | - `rights.ends_at` is 00:00 UTC of the last day of your export rights for the film. That day is included: stop using the creative after that UTC day ends, at `ends_at + 86400`. - - ## Versioning - - Each record carries `schema_version`, currently `1`. New fields can be added without changing it, so ignore fields you do not recognise. + Every field: [List creatives](../reference/creatives-list.md#the-creative-record). Each record carries `schema_version` (currently `1`); new fields are added without changing it, so ignore fields you do not recognise. - ## Rate limits + ## Related {#related} - The two creatives endpoints share one rate-limit counter, separate from the catalog. A sync a few times an hour is well within it. See [Rate limits](rate-limits.md). + - [Creatives sync](../guides/creatives-sync.md) + - [When rights end](../production/rights-end.md)
- 1 Oct 2026 · +1 −1 lines
Show changes
⋯ ## Rate limits - The creatives endpoints share one rate-limit counter with the catalog endpoint. A sync a few times an hour is well within it. See [Rate limits](rate-limits.md). + The two creatives endpoints share one rate-limit counter, separate from the catalog. A sync a few times an hour is well within it. See [Rate limits](rate-limits.md).
- 1 Oct 2026 · +3 −3 lines
Show changes
⋯ 1. **First sync.** Call `GET /creatives?limit=100` without `updated_since`. While `data.next_cursor` is not `null`, call again with `cursor=<next_cursor>`. 2. **Save a checkpoint.** Keep the largest `updated_at` you received. - 3. **Later syncs.** Call with `updated_since=<checkpoint>` and page through with `cursor` again. Only records updated after that time are returned. + 3. **Later syncs.** Call with `updated_since=<checkpoint>` and page through with `cursor` again. Only records updated strictly after that second (`>`) are returned. ```bash ⋯ | `duration_ms` | Total length of the clips used. | | `formula` | The formula the creative was built with, if any. | - | `rights.ends_at` | When your export rights for the film end, or `null`. | + | `rights.ends_at` | The last day of your export rights for the film (00:00 UTC of that day), or `null`. | | `lineage.parent_creative_id` | The creative this one was derived from, if any. | | `final.ready` | Whether the final render exists. | - `rights.ends_at` marks the last day of your export rights for the film. Stop using the creative once that day has passed. + `rights.ends_at` is 00:00 UTC of the last day of your export rights for the film. That day is included: stop using the creative after that UTC day ends, at `ends_at + 86400`. ## Versioning ⋯
- 1 Oct 2026 · +1 −1 lines
Show changes
⋯ The feed returns creatives that belong to your organisation and have status `approved` or `pushed` (already delivered). Creatives in any other status, such as drafts, are not included. Creatives of other organisations are never visible. - A record never contains a media URL. The feed describes the creative; final video files are not delivered through this API. Ask your Wandura partner contact how final files reach your systems. + A record never contains a media URL. The feed describes the creative; final video files are not delivered through this API. Ask Wandura how final files reach your systems. `final.ready` tells you whether the final render of the creative exists yet. ⋯
- 29 Sept 2026 · Page created