List creatives

Returns a page of approved creatives of your organisation, each as a full data record. Use it to sync creatives into your marketing systems, incrementally with updated_since.

GET /api/delivery/v1/creatives

Scope: creatives:export

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.

Request parameters

Name	In	Type	Required	Description
`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 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. 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

curl -s "https://www.wandura.ai/api/delivery/v1/creatives?updated_since=1790600000&limit=2" \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response

200 OK

Field	Type	Description
`code`	integer	`0`.
`message`	string	`"ok"`.
`data.items`	array	The creative records on this page. See The creative record.
`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.

The creative record

The same record is returned by Get a creative.

Field	Type	Description
`schema_version`	integer	Record schema version. Currently `1`.
`creative_id`	string (UUID)	Stable creative ID.
`creative_code`	string or null	Immutable human-readable code. Treat it as opaque.
`name`	string	Creative name.
`status`	string	`approved`, or `pushed` once delivered.
`created_at`	integer	Creation time, Unix seconds.
`approved_at`	integer or null	Approval time, Unix seconds.
`updated_at`	integer	Last update, Unix seconds, rounded down.
`org.slug`	string	Your organisation's slug.
`film`	object or null	The film the creative is cut from.
`film.code`	string or null	Film code.
`film.title`	string or null	Film title.
`film.language`	string or null	Film language.
`film.genres`	array of strings	Film genres. Can be empty.
`episodes`	array of integers	Episode numbers used, without duplicates.
`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.
`scenes`	array	The film clips used, in order.
`scenes[].episode_no`	integer or null	Episode the clip comes from.
`scenes[].start_ms`	integer	Clip start in the episode, milliseconds.
`scenes[].end_ms`	integer	Clip end in the episode, milliseconds.
`scenes[].duration_ms`	integer	Clip length, milliseconds.
`scenes[].action`	string or null	Action label of the scene, for example `reveal`, `argue`, `slap`, `kiss`, `embrace`, `cry`, `kneel`, `walk_away` or `violence`. `null` when the scene has no notable action. New labels may be added.
`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.
`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. 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.

Response example

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "schema_version": 1,
        "creative_id": "5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d",
        "creative_code": "ACV001-FILM0001-EP1-2-F1-TEAM",
        "name": "Heiress returns - wedding hook",
        "status": "approved",
        "created_at": 1790500000,
        "approved_at": 1790590000,
        "updated_at": 1790610000,
        "org": { "slug": "your-org" },
        "film": { "code": "FILM0001", "title": "The Heiress Returns", "language": "en", "genres": ["romance", "revenge"] },
        "episodes": [1, 2],
        "placement": "reels_9x16",
        "aspect": "9:16",
        "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": 2, "start_ms": 40000, "end_ms": 54000, "duration_ms": 14000, "action": null, "line": null }
        ],
        "hook": { "action": "reveal", "line": "You threw me out. Now watch me take it all back." },
        "formula": { "name": "Cliffhanger opener" },
        "rights": { "ends_at": 1798675200 },
        "lineage": { "parent_creative_id": null },
        "final": { "ready": true, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } }
      }
    ],
    "next_cursor": "eyJwIjoiZXhhbXBsZS1jdXJzb3IifQ"
  },
  "server_time": 1790679032
}

Errors

Status	`code`	When
401	4010	The `Authorization: Bearer` header is missing.
401	4011	The key is unknown or revoked.
403	4030	The key lacks the `creatives:export` scope.
403	4031	Your organisation's access is suspended.
422	4220	`limit` is not an integer between 1 and 100.
422	4221	`updated_since` is not epoch seconds.
422	4222	`cursor` is not valid.
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 for what to do in each case.

List creatives

Description#

Request parameters#

Request example#

Response#

The creative record#

Response example#

Errors#