GET/api/v1/banners/:id

Get a banner

Reads the spec, the current version, the pieces and the texts of a concept, or lists the concepts in your workspace.

Returns only data: the concept's spec, the current version, the status of each piece (size by locale) and the texts by locale. It does not return HTML or preview links. Requires the read permission (or any of the others, which include it).

Path parameters

FieldRequirementDescription

idstring

Required

The creativeId: you see it in the finished job and in the banner.generated webhook.

Response

FieldWhat it is

id, campaignId, name

Identify the concept, its campaign and its name.

variantNo, versionNo

Alternative number (variant) and version number.

appUrl

Absolute link to the concept in the app's studio. null with a test key.

specVersion, engineVersion, modelId

Which spec version, engine version and model produced this version.

spec

The technical description of the concept in JSON: composition, texts and animation.

pieces

One entry per piece (a size in one locale), with size, locale and status.

translations

The texts by locale.

createdAt

Creation date in ISO 8601 format.

A piece's status is draft, in_review, changes, approved or needs_review.

List concepts

GET /api/v1/banners lists the workspace's concepts, newest first, with cursor pagination (cursor and limit, from 1 to 100; default 50). Filter with campaignId. Each item carries id, campaignId, name, variantNo, versionNo, url and appUrl.

Errors

An id that does not exist, or that belongs to another workspace, responds 404. Test ids (crt_test_…) can only be read with bm_test_ keys.

Job statusCheck a generation job or follow it live with SSE events.CampaignsList the campaigns in your workspace, archive them, and add or remove locales.Correct and adapt a bannerCorrect a concept with a plain-language instruction or add new sizes to it. They respond 202 with a job.

Was this page helpful?