Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 19 Oct 2026 · +4 −4 lines
Show changes
⋯ ## Description - Returns creatives of your organisation with status `approved` or `pushed`, ordered by `updated_at` ascending and then by ID. Records never contain a media URL. Successful responses are wrapped in the `{code, message, data, server_time}` envelope; errors use the same envelope without `data`, except `429` and `400` `unsupported_version`, which use the flat format. See [Creatives](../concepts/creatives.md). + Returns creatives of your organisation with status `approved` or `pushed`, ordered by `updated_at` ascending and then by ID. Records never contain a signed media URL. Successful responses are wrapped in the `{code, message, data, server_time}` envelope; errors use the same envelope without `data`, except `429` and `400` `unsupported_version`, which use the flat format. See [Creatives](../concepts/creatives.md). ## Request parameters ⋯ ### The creative record - The same record is returned by [Get a creative](creatives-get.md). `final.file_url` is the durable API URL that downloads the final video: call it with your API key; it redirects to a download link valid for 15 minutes ([Download a creative's final file](creatives-file.md)). It is `null` until `final.ready` is `true`. + The same record is returned by [Get a creative](creatives-get.md). `final.file_url` is the creative's public share link: no API key needed, durable, and revocable in the portal. Each open redirects to a fresh download link valid for 15 minutes, so you can hand it to Meta's video upload. It is `null` until `final.ready` is `true`, and `null` when an admin of your organisation revoked the link. See [Downloading the final file](../concepts/creatives.md#downloading-the-final-file); to download with your API key instead, use [Download a creative's final file](creatives-file.md). | Field | Type | Description | ⋯ | `lineage.parent_creative_id` | string (UUID) or null | The creative this one was derived from. | | `final.ready` | boolean | Whether the final render exists. A creative in status `pushed` has one. | - | `final.file_url` | string or null | Durable API URL to download the final video (`GET /api/delivery/v1/creatives/{id}/file`); `null` until `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. It is an API URL, not a media URL: you may store it. | + | `final.file_url` | string or null | 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. Format `https://www.wandura.ai/api/c/{token}.mp4`; every open re-checks that the creative is still approved and your export rights for the film are active (`410` otherwise). The file is the clean final, with your company's brand mark if your org has one. `null` until `ready` is `true`, and `null` when an admin of your organisation revoked the link: ask your admin, or create a new share link in the portal. Anyone holding the link can download the file, so treat it like a password. To download with your API key instead, call `GET /api/delivery/v1/creatives/{id}/file`. | | `final.target` | object | Target render spec: `width`, `height`, `fps`, `codec`. Today it is the same for every creative (1080 × 1920, 30 fps, `h264`) and does not follow `placement`, so do not derive the frame size from it. | ⋯ "final": { "ready": true, - "file_url": "https://www.wandura.ai/api/delivery/v1/creatives/5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d/file", + "file_url": "https://www.wandura.ai/api/c/Q3vh0xAbCdEfGhIjKlMnOpQrStUvWx9f.mp4", "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } } ⋯
- 19 Oct 2026 · +7 −2 lines
Show changes
⋯ ### The creative record - The same record is returned by [Get a creative](creatives-get.md). + The same record is returned by [Get a creative](creatives-get.md). `final.file_url` is the durable API URL that downloads the final video: call it with your API key; it redirects to a download link valid for 15 minutes ([Download a creative's final file](creatives-file.md)). It is `null` until `final.ready` is `true`. | Field | Type | Description | ⋯ | `lineage.parent_creative_id` | string (UUID) or null | The creative this one was derived from. | | `final.ready` | boolean | Whether the final render exists. A creative in status `pushed` has one. | + | `final.file_url` | string or null | Durable API URL to download the final video (`GET /api/delivery/v1/creatives/{id}/file`); `null` until `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. It is an API URL, not a media URL: you may store it. | | `final.target` | object | Target render spec: `width`, `height`, `fps`, `codec`. Today it is the same for every creative (1080 × 1920, 30 fps, `h264`) and does not follow `placement`, so do not derive the frame size from it. | ⋯ "rights": { "ends_at": 1798675200 }, "lineage": { "parent_creative_id": null }, - "final": { "ready": true, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } } + "final": { + "ready": true, + "file_url": "https://www.wandura.ai/api/delivery/v1/creatives/5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d/file", + "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } + } } ], ⋯
- 19 Oct 2026 · +4 −0 lines
Show changes
⋯ | `updated_at` | integer | Last update, Unix seconds, rounded down. | | `org.slug` | string | Your organisation's slug. | + | `created_by` | object or null | The user who created the creative. `null` when the creator is unknown, for example a creative made by the system or by a user whose account was deleted. | + | `created_by.email` | string | Email of the creator. | + | `created_by.name` | string or null | Display name of the creator. `null` when the creator has not set a name. | | `film` | object or null | The film the creative is cut from. | | `film.code` | string or null | Film code. | ⋯ "updated_at": 1790610000, "org": { "slug": "your-org" }, + "created_by": { "email": "maker@example.com", "name": "Alex Tran" }, "film": { "code": "FILM0001", "title": "The Heiress Returns", "language": "en", "genres": ["romance", "revenge"] }, "episodes": [1, 2], ⋯
- 2 Oct 2026 · +2 −1 lines
Show changes
⋯ | `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. | | `Wandura-Version` | all | The dated API version (YYYY-MM-DD) this response was produced in: the version pinned to your API key, or the one you sent in the `Wandura-Version` request header. Keys created before dated versions existed use `2026-10-02`. | + | `Wandura-Request-Id` | all | An opaque id for this request (`req_` followed by 26 characters). Every response carries it, errors included, and error bodies repeat it as `request_id`. Log it, and quote it when you contact Wandura about a request: it finds the exact request in our logs. Do not parse it. | | `Deprecation` | 200 | Present only when this endpoint, or the dated version serving this response, is deprecated (RFC 9745): `@<unix seconds>` of the deprecation date. Log it in your monitoring. | | `Sunset` | 200 | Present only when a deprecated endpoint or dated version has a date when it stops working (RFC 8594), as an HTTP date. | | `Link` | 200 | Present with `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (and `rel="sunset"`) pointing to the page that explains what to use instead. | - | `Cache-Control` | 200, 401, 403, 422, 503 | Always `no-store`. Do not cache these responses in shared caches. | + | `Cache-Control` | all | Always `no-store`. Do not cache these responses in shared caches. | | `Retry-After` | 429 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. | | `X-RateLimit-Limit` | 429 | Requests (for playback, tickets) allowed per window for this endpoint group and your organisation. | ⋯
- 2 Oct 2026 · +1 −1 lines
Show changes
⋯ ## Description - Returns creatives of your organisation with status `approved` or `pushed`, ordered by `updated_at` ascending and then by ID. Records never contain a media URL. Every response, success or error (except `429`), is wrapped in the `{code, message, data, server_time}` envelope. See [Creatives](../concepts/creatives.md). + Returns creatives of your organisation with status `approved` or `pushed`, ordered by `updated_at` ascending and then by ID. Records never contain a media URL. Successful responses are wrapped in the `{code, message, data, server_time}` envelope; errors use the same envelope without `data`, except `429` and `400` `unsupported_version`, which use the flat format. See [Creatives](../concepts/creatives.md). ## Request parameters ⋯
- 2 Oct 2026 · +10 −0 lines
Show changes
⋯ | `cursor` | query | string | No | The `next_cursor` from the previous page. Opaque; pass it back unchanged. | | `limit` | query | integer | No | Records per page, 1 to 100. Default `50`. | + | `Wandura-Version` | header | string | No | Optional. A dated API version (YYYY-MM-DD) to use for this request instead of the version pinned to your API key. Unknown or retired values answer 400 with `error_code` `unsupported_version`. | You can combine `updated_since` and `cursor`. Keep the same `updated_since` on every page of one sync. Because `updated_at` in each record is rounded down to the second, passing the largest `updated_at` you received usually returns the last records again; overwrite them by `creative_id`. ⋯ | `data.next_cursor` | string or null | Pass it as `cursor` to get the next page. `null` on the last page. | | `server_time` | integer | Server time in Unix epoch seconds. | + | `links` | object | Ready-made absolute URLs of this page — follow `links.next` instead of building the next-page URL. | + | `links.self` | string | This request. | + | `links.next` | string or null | The next page, or `null` on the last page. | ### The creative record ⋯ | Field | Type | Description | |---|---|---| + | `links` | object | Ready-made absolute URL of this creative's own endpoint (an API link, not a media URL). | | `schema_version` | integer | Record schema version. Currently `1`. Additive fields do not change it. | | `creative_id` | string (UUID) | Stable creative ID. | ⋯ |---|---|---| | `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. | + | `Wandura-Version` | all | The dated API version (YYYY-MM-DD) this response was produced in: the version pinned to your API key, or the one you sent in the `Wandura-Version` request header. Keys created before dated versions existed use `2026-10-02`. | + | `Deprecation` | 200 | Present only when this endpoint, or the dated version serving this response, is deprecated (RFC 9745): `@<unix seconds>` of the deprecation date. Log it in your monitoring. | + | `Sunset` | 200 | Present only when a deprecated endpoint or dated version has a date when it stops working (RFC 8594), as an HTTP date. | + | `Link` | 200 | Present with `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (and `rel="sunset"`) pointing to the page that explains what to use instead. | | `Cache-Control` | 200, 401, 403, 422, 503 | Always `no-store`. Do not cache these responses in shared caches. | | `Retry-After` | 429 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. | ⋯ | Status | `code` | When | |---|---|---| + | 400 | none | The `Wandura-Version` header, or the version pinned to your key, is unknown or retired. The body adds `supported_versions` and `latest_version` (and `upgrade_to` when your pin was retired). | | 401 | 4010 | The `Authorization: Bearer` header is missing. | | 401 | 4011 | The key is unknown or revoked. | ⋯
- 2 Oct 2026 · +23 −5 lines
Show changes
⋯ | `code` | integer | `0`. | | `message` | string | `"ok"`. | - | `data.items` | array | The creative records on this page. See [The creative record](#the-creative-record). | + | `data.items` | array | The creative records on this page. | | `data.next_cursor` | string or null | Pass it as `cursor` to get the next page. `null` on the last page. | | `server_time` | integer | Server time in Unix epoch seconds. | ⋯ | Field | Type | Description | |---|---|---| - | `schema_version` | integer | Record schema version. Currently `1`. | + | `schema_version` | integer | Record schema version. Currently `1`. Additive fields do not change it. | | `creative_id` | string (UUID) | Stable creative ID. | | `creative_code` | string or null | Immutable human-readable code. Treat it as opaque. | ⋯ | `placement` | string or null | `reels_9x16`, `feed_4x5` or `square_1x1`. | | `aspect` | string or null | `9:16`, `4:5` or `1:1`, matching `placement`. | - | `duration_ms` | integer | Total length of the film clips used, in milliseconds. | + | `duration_ms` | integer | Total length of the film clips used, in milliseconds. Can be shorter than the final video, because `scenes` lists only clips taken from film episodes. | | `scenes` | array | The film clips used, in order. | | `scenes[].episode_no` | integer or null | Episode the clip comes from. | ⋯ | `scenes[].line` | string or null | The spoken line or standout line of the scene. | | `hook` | object or null | `action` and `line` of the first scene. `null` when there are no scenes. | - | `formula` | object or null | `{ "name": ... }` of the formula the creative was built with. | + | `formula` | object or null | The formula the creative was built with. | + | `formula.name` | string | Formula name. | | `rights.ends_at` | integer or null | Last day of your export rights for the film, as Unix seconds at 00:00 UTC of that day. Your rights include that whole day: stop using the creative after that UTC day ends, that is at `ends_at + 86400`. `null` when Wandura has no end date on record for your export rights. | | `lineage.parent_creative_id` | string (UUID) or null | The creative this one was derived from. | ⋯ "duration_ms": 21500, "scenes": [ - { "episode_no": 1, "start_ms": 12000, "end_ms": 19500, "duration_ms": 7500, "action": "reveal", "line": "You threw me out. Now watch me take it all back." }, + { + "episode_no": 1, + "start_ms": 12000, + "end_ms": 19500, + "duration_ms": 7500, + "action": "reveal", + "line": "You threw me out. Now watch me take it all back." + }, { "episode_no": 2, "start_ms": 40000, "end_ms": 54000, "duration_ms": 14000, "action": null, "line": null } ], ⋯ ``` + ## Response headers {#response-headers} + + | Header | Responses | Description | + |---|---|---| + | `Wandura-API-Status` | all | API status. `beta` today, on every response, success or error. | + | `Cache-Control` | 200, 401, 403, 422, 503 | Always `no-store`. Do not cache these responses in shared caches. | + | `Retry-After` | 429 | Seconds to wait before retrying. Sent with 429 and with retryable 503 responses. | + | `X-RateLimit-Limit` | 429 | Requests (for playback, tickets) allowed per window for this endpoint group and your organisation. | + | `X-RateLimit-Window` | 429 | Window length in seconds. | + ## Errors ⋯
- 1 Oct 2026 · +6 −5 lines
Show changes
⋯ |---|---|---|---|---| | `Authorization` | header | string | Yes | `Bearer <API key>` for a key with the `creatives:export` scope. | - | `updated_since` | query | integer | No | Unix epoch seconds (up to 11 digits). Returns only records updated after this time. | + | `updated_since` | query | integer | No | Unix epoch seconds (up to 11 digits). Returns only records whose exact update time is strictly after this second (`>`, not `>=`). | | `cursor` | query | string | No | The `next_cursor` from the previous page. Opaque; pass it back unchanged. | | `limit` | query | integer | No | Records per page, 1 to 100. Default `50`. | - You can combine `updated_since` and `cursor`. Keep the same `updated_since` on every page of one sync. + You can combine `updated_since` and `cursor`. Keep the same `updated_since` on every page of one sync. Because `updated_at` in each record is rounded down to the second, passing the largest `updated_at` you received usually returns the last records again; overwrite them by `creative_id`. ## Request example ⋯ | `hook` | object or null | `action` and `line` of the first scene. `null` when there are no scenes. | | `formula` | object or null | `{ "name": ... }` of the formula the creative was built with. | - | `rights.ends_at` | integer or null | Last day of your export rights for the film, as Unix seconds at 00:00 UTC of that day. `null` when Wandura has no end date on record for your export rights. | + | `rights.ends_at` | integer or null | Last day of your export rights for the film, as Unix seconds at 00:00 UTC of that day. Your rights include that whole day: stop using the creative after that UTC day ends, that is at `ends_at + 86400`. `null` when Wandura has no end date on record for your export rights. | | `lineage.parent_creative_id` | string (UUID) or null | The creative this one was derived from. | - | `final.ready` | boolean | Whether the final render exists. | - | `final.target` | object | Target render spec: `width`, `height`, `fps`, `codec`. | + | `final.ready` | boolean | Whether the final render exists. A creative in status `pushed` has one. | + | `final.target` | object | Target render spec: `width`, `height`, `fps`, `codec`. Today it is the same for every creative (1080 × 1920, 30 fps, `h264`) and does not follow `placement`, so do not derive the frame size from it. | `scenes` lists only clips taken from film episodes. Other elements of the creative are not listed, so `duration_ms` can be shorter than the final video. ⋯ | 429 | none | Rate limit reached. Flat body with `error_code` `rate_limited`, not the envelope. | | 503 | 5030 | The feed is temporarily unavailable. Retry with backoff. | + | 503 | 5031 | Wandura could not verify the API key in time. The key is not wrong: retry with backoff. | See [Errors](../concepts/errors.md#creatives-errors) for what to do in each case.
- 29 Sept 2026 · Page created