Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 19 Oct 2026 · +19 −8 lines
Show changes
# Creatives - > **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, and download each final video with your API key from `final.file_url`. + > **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 signed media URL. Sync them incrementally with `updated_since` and a cursor. Each record's `final.file_url` is a public share link to the final video: no API key needed, so you can hand it straight to Meta's video upload. ## What the feed contains {#what-the-feed-contains} ⋯ | [`GET /api/delivery/v1/creatives`](../reference/creatives-list.md) | Sync all records, incrementally. | | [`GET /api/delivery/v1/creatives/{id}`](../reference/creatives-get.md) | Fetch or re-check one record. | - | [`GET /api/delivery/v1/creatives/{id}/file`](../reference/creatives-file.md) | Download the final video. | + | [`GET /api/delivery/v1/creatives/{id}/file`](../reference/creatives-file.md) | Download the final video with your API key, instead of the share link in `final.file_url`. | All three need a key with `creatives:export` ([Authentication](../authentication.md#scopes)) and share one rate-limit counter. ⋯ | `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. | - | `final.file_url` | Durable API URL to download the final video; `null` until `final.ready` is `true`. Call it with your API key; it redirects to a download link valid for 15 minutes. The file is the clean final, with your company's brand mark if your org has one. | + | `final.file_url` | Public, durable download link (no API key needed), revocable in the portal; each open redirects to a fresh 15-minute download link. Safe to hand to Meta's video upload. `null` until `final.ready` is `true`, and `null` when an admin of your organisation revoked the link. The file is the clean final, with your company's brand mark if your org has one. | 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. ⋯ ## Downloading the final file {#downloading-the-final-file} - When `final.ready` is `true`, call `final.file_url` with your API key. It answers `302` with a download link valid for 15 minutes; most HTTP clients follow it for you: + When `final.ready` is `true`, `final.file_url` is the creative's [share link](../../partners/creatives.md#share-link), such as `https://www.wandura.ai/api/c/Q3vh0xAbCdEfGhIjKlMnOpQrStUvWx9f.mp4`. It needs no API key. Each open answers `302` with a fresh download link valid for 15 minutes, so tools that fetch a file by URL, such as Meta's video upload (`file_url`), can use it directly, however long your campaign setup takes: ```bash - curl -sL -o final.mp4 "$FILE_URL" -H "Authorization: Bearer $WANDURA_API_KEY" + curl -sL -o final.mp4 "$FILE_URL" ``` - - Store `final.file_url`, never the download link: the link expires, the API URL does not. Call it again for a fresh link. + - Store `final.file_url`, never the download link it redirects to: the download link expires after 15 minutes, the share link does not. + - Anyone holding the share link can download the file. Treat it like a password: do not publish it. + - Every open re-checks that the creative is still approved and that your export rights for the film are active; otherwise it answers `410`. An admin of your organisation can revoke the link in the portal, and it then answers `410` at once. + - After a revoke, the record's `final.file_url` is `null`. Revoking does not change `updated_at`, so an incremental sync does not pick it up: when a stored link answers `410`, call [Get a creative](../reference/creatives-get.md) for the current link. Still `null`? Ask your admin, or create a new share link in the portal. + - Each link allows 120 opens per minute; beyond that it answers `429` with `Retry-After`. - The file is an MP4, 1080 × 1920: the clean final, with your company's brand mark if your org has one. + + ### Downloading with your API key {#downloading-with-your-api-key} + + [`GET /api/delivery/v1/creatives/{id}/file`](../reference/creatives-file.md) downloads the same file with your API key instead of a share link. It answers `302` with a download link valid for 15 minutes; most HTTP clients follow it for you: + + ```bash + curl -sL -o final.mp4 "https://www.wandura.ai/api/delivery/v1/creatives/$CREATIVE_ID/file" -H "Authorization: Bearer $WANDURA_API_KEY" + ``` + - `409` with `code` `4090` means the final is not ready yet. After your export rights end, it answers `403` with `code` `4032`. - Every download is logged against your API key. If a key leaks, revoke it: it can download every final of your organisation until then. - Details: [Download a creative's final file](../reference/creatives-file.md). - ## Related {#related} ⋯
- 19 Oct 2026 · +20 −3 lines
Show changes
# Creatives - > **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. + > **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, and download each final video with your API key from `final.file_url`. ## What the feed contains {#what-the-feed-contains} - 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. + 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; once it does, [download it](#downloading-the-final-file) from `final.file_url`. ## Endpoints {#endpoints} ⋯ | [`GET /api/delivery/v1/creatives`](../reference/creatives-list.md) | Sync all records, incrementally. | | [`GET /api/delivery/v1/creatives/{id}`](../reference/creatives-get.md) | Fetch or re-check one record. | + | [`GET /api/delivery/v1/creatives/{id}/file`](../reference/creatives-file.md) | Download the final video. | - Both need a key with `creatives:export` ([Authentication](../authentication.md#scopes)) and share one rate-limit counter. + All three need a key with `creatives:export` ([Authentication](../authentication.md#scopes)) and share one rate-limit counter. ## Response envelope {#response-envelope} ⋯ | `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. | + | `final.file_url` | Durable API URL to download the final video; `null` until `final.ready` is `true`. Call it with your API key; it redirects to a download link valid for 15 minutes. The file is the clean final, with your company's brand mark if your org has one. | 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. + ## Downloading the final file {#downloading-the-final-file} + + When `final.ready` is `true`, call `final.file_url` with your API key. It answers `302` with a download link valid for 15 minutes; most HTTP clients follow it for you: + + ```bash + curl -sL -o final.mp4 "$FILE_URL" -H "Authorization: Bearer $WANDURA_API_KEY" + ``` + + - Store `final.file_url`, never the download link: the link expires, the API URL does not. Call it again for a fresh link. + - The file is an MP4, 1080 × 1920: the clean final, with your company's brand mark if your org has one. + - `409` with `code` `4090` means the final is not ready yet. After your export rights end, it answers `403` with `code` `4032`. + - Every download is logged against your API key. If a key leaks, revoke it: it can download every final of your organisation until then. + + Details: [Download a creative's final file](../reference/creatives-file.md). + ## Related {#related} ⋯
- 19 Oct 2026 · +1 −0 lines
Show changes
⋯ | `creative_id` | Stable ID. Your primary key. | | `creative_code` | Immutable human-readable code; treat it as opaque. | + | `created_by` | Who made the creative: `email`, and `name` (or `null` when no name is set). `null` when the creator is unknown, for example a creative made by the system. | | `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. | ⋯
- 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