Skip to main content
Creatives represent the content variant of an offer delivered through a specific channel. Each creative is linked to exactly one offer and one channel, and optionally to a placement within that channel.
See the Creatives feature page for UI guidance and conceptual overview.

​
Base path

/api/v1/creatives

​
List creatives

GET /api/v1/creatives
Returns a paginated list of creatives for the current tenant, ordered by creation date (newest first). Each creative includes its parent offer, channel, and placement relations.

​
Query parameters

ParameterRequiredTypeDescription
limitNointegerMaximum results per page. Default 25.
cursorNostringCursor for keyset pagination.

​
Response 200

{
  "data": [
    {
      "id": "cre_abc123",
      "tenantId": "t_001",
      "name": "Platinum Card - Email Hero",
      "offerId": "off_001",
      "channelId": "ch_email",
      "placementId": null,
      "status": "active",
      "templateType": "email_html",
      "content": {
        "subject": "Your exclusive upgrade awaits",
        "body": "<html>...</html>"
      },
      "personalization": [
        { "key": "first_name", "source": "customer.first_name" }
      ],
      "constraints": {},
      "abTestVariant": null,
      "weight": 100,
      "metrics": {},
      "offer": { "id": "off_001", "name": "Platinum Card Upgrade" },
      "channel": { "id": "ch_email", "name": "Email" },
      "placement": null,
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 18,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

​
Create a creative

POST /api/v1/creatives
Creates a new creative and triggers auto-assembly.

​
Request body

FieldRequiredTypeDescription
nameYesstring (1-255)Unique creative name.
offerIdYesstringParent offer ID.
channelIdYesstringTarget channel ID.
placementIdNostring | nullPlacement within the channel. Default null.
statusNoenumdraft (default), active, paused, archived.
templateTypeNostringTemplate format. Default "email_html".
contentNoobjectTemplate content (subject, body, image URLs, etc.).
personalizationNoarrayPersonalization token mappings. Max 500 items.
constraintsNoobjectDelivery constraints (time-of-day, frequency).
abTestVariantNostring | nullA/B test variant label.
weightNointeger (0-100)Traffic weight for multi-variant rotation. Default 100.
metricsNoobjectPerformance metric overrides.

​
Example request

{
  "name": "Platinum Card - Email Hero",
  "offerId": "off_001",
  "channelId": "ch_email",
  "templateType": "email_html",
  "content": {
    "subject": "Your exclusive upgrade awaits",
    "body": "<html>...</html>"
  },
  "personalization": [
    { "key": "first_name", "source": "customer.first_name" }
  ],
  "weight": 100
}

​
Response 201

Returns the created creative with offer, channel, and placement relations.

​
Error codes

CodeReason
400Validation error (missing offerId, channelId, or name).
409A creative with that name already exists.
415Content-Type is not application/json.

​
Update a creative

PUT /api/v1/creatives
Updates an existing creative. Only provided fields are changed.

​
Request body

All fields from the create schema are accepted as optional, plus:
FieldRequiredTypeDescription
idYesstringThe creative ID to update.

​
Example request

{
  "id": "cre_abc123",
  "status": "active",
  "weight": 80
}

​
Response 200

Returns the updated creative object.

​
Delete a creative

DELETE /api/v1/creatives?id={creativeId}
Deletes a creative by ID.

​
Query parameters

ParameterRequiredTypeDescription
idYesstringCreative ID to delete.

​
Response 204

Empty body on success.

​
Error codes

CodeReason
400Missing id query parameter.

​
Role requirements

MethodMinimum role
GETviewer
POSTeditor
PUTeditor
DELETEeditor

Creatives

Learn more about creating and managing creatives in the platform UI.