Creatives API

Create, update, list, and delete creatives (treatments) linked to offers and channels.

See also: Creatives concept and configuration for what this API powers, when to call it, and how it is configured.

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.

All creatives support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).

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. By default, soft-deleted creatives are excluded.

Query parameters

Parameter	Required	Type	Description
limit	No	integer	Maximum results per page. Default 25.
cursor	No	string	Cursor for keyset pagination.
includeDeleted	No	string	Set to "true" to include soft-deleted creatives in the results.

Response 200

{
  "data": [
    {
      "id": "cre_abc123",
      "tenantId": "t_001",
      "name": "Platinum Card - Email Hero",
      "offerId": "off_001",
      "channelId": "ch_email",
      "placementId": "pl_email_hero",
      "contentItemId": null,
      "status": "active",
      "templateType": "email_html",
      "content": {
        "subject": "You're pre-approved for a higher limit",
        "headline": "Hey {first_name}, lift your limit to {recommended_credit_limit}",
        "body": "<p>Your Platinum status pre-qualifies you for a credit-limit increase...</p>",
        "ctaText": "Accept upgrade",
        "ctaUrl": "https://example.com/accept"
      },
      "personalization": [
        { "variable": "first_name", "fallback": "valued customer", "source": "customer.first_name" },
        { "variable": "recommended_credit_limit", "fallback": "$5,000", "source": "personalization.recommended_credit_limit" }
      ],
      "constraints": {
        "frequencyCapPerDay": 3,
        "cooldownHours": 24,
        "priorityOverride": 50
      },
      "abTestVariant": null,
      "weight": 100,
      "metrics": {},
      "version": 1,
      "deletedAt": null,
      "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
  }
}

Error codes

Code	Reason
401	Missing or invalid API key / session.
403	Insufficient role.

---

Create a creative

POST /api/v1/creatives

Creates a new creative and triggers auto-assembly.

Request body

Field	Required	Type	Description
name	Yes	string (1-255)	Unique creative name.
offerId	Yes	string	Parent offer ID.
channelId	Yes	string	Target channel ID.
placementId	No	string | null	Placement within the channel. When set, the creative becomes a candidate ONLY for that placement (per-(offer, placement) candidate expansion → Hungarian assignment). When null, it’s a wildcard candidate across every placement on the channel. Default null.
status	No	enum	draft (default), active, paused, archived.
templateType	No	string	Template format. Common values: email_html, push_notification, sms_text, in_app_modal, banner, content_card, webhook_json, whatsapp_template. Default "email_html".
content	No	object	Template content. Typical fields: subject, headline, body, imageUrl, ctaText, ctaUrl, deepLink. Tokens like {first_name} are substituted at delivery time using the personalization mappings.
personalization	No	array	Personalization token mappings — each entry is { variable, fallback, source }. variable is the token name used in content (e.g. first_name for {first_name}); source is the data path (customer.*, attributes.*, personalization.* for computed values); fallback is rendered when the source resolves to null/undefined. Max 500 items.
constraints	No	object	Delivery constraints. Typical fields: frequencyCapPerDay (integer), cooldownHours (integer), priorityOverride (0–100).
abTestVariant	No	string | null	A/B test variant label (e.g. "control", "variant_a").
weight	No	integer (0-100)	Traffic weight for multi-variant rotation. Default 100.
metrics	No	object	Performance metric overrides.

Example request

{
  "name": "Platinum Card - Email Hero",
  "offerId": "off_001",
  "channelId": "ch_email",
  "placementId": "pl_email_hero",
  "templateType": "email_html",
  "content": {
    "subject": "You're pre-approved for a higher limit",
    "headline": "Hey {first_name}, lift your limit to {recommended_credit_limit}",
    "body": "<p>Your Platinum status pre-qualifies you for a credit-limit increase up to <strong>{recommended_credit_limit}</strong>.</p>",
    "ctaText": "Accept upgrade",
    "ctaUrl": "https://example.com/accept-platinum-upgrade"
  },
  "personalization": [
    { "variable": "first_name", "fallback": "valued customer", "source": "customer.first_name" },
    { "variable": "recommended_credit_limit", "fallback": "$5,000", "source": "personalization.recommended_credit_limit" }
  ],
  "constraints": {
    "frequencyCapPerDay": 3,
    "cooldownHours": 24,
    "priorityOverride": 50
  },
  "abTestVariant": "control",
  "weight": 100
}

Response 201

Returns the created creative with offer, channel, and placement relations, version: 1, and deletedAt: null. An audit log entry is created with a create action.

Error codes

Code	Reason
400	Validation error (missing offerId, channelId, or name).
401	Missing or invalid API key / session.
403	Insufficient role (requires editor or admin).
409	A creative with that name already exists.
415	Content-Type is not application/json.

---

Update a creative

PUT /api/v1/creatives

Updates an existing creative. Only provided fields are changed. The version field is auto-incremented and a before/after audit snapshot is recorded.

Request body

All fields from the create schema are accepted as optional, plus:

Field	Required	Type	Description
id	Yes	string	The creative ID to update.

Example request

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

Response 200

Returns the updated creative object with the incremented version.

Error codes

Code	Reason
400	Validation error.
401	Missing or invalid API key / session.
403	Insufficient role.
409	A creative with that name already exists.

---

Delete a creative (soft-delete)

DELETE /api/v1/creatives?id={creativeId}

Soft-deletes a creative by setting its deletedAt timestamp. The version is incremented. Creatives have no cascade children.

Query parameters

Parameter	Required	Type	Description
id	Yes	string	Creative ID to delete.

Response 200

{
  "success": true,
  "id": "cre_abc123"
}

Error codes

Code	Reason
400	Missing id query parameter, entity not found, or entity already deleted.
401	Missing or invalid API key / session.
403	Insufficient role.

To restore a soft-deleted creative, use POST /api/v1/restore?entityType=creative&id={creativeId} (admin only).

---

Role requirements

Method	Minimum role
GET	viewer
POST	editor
PUT	editor
DELETE	editor

Creatives

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