Documentation Index Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
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).
Base path List 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 limitNo integer Maximum results per page. Default 25. cursorNo string Cursor for keyset pagination. includeDeletedNo 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" : null , "contentItemId" : 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" : {}, "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 401Missing or invalid API key / session. 403Insufficient role.
Create a creative Creates a new creative and triggers auto-assembly.
Request body Field Required Type Description nameYes string (1-255) Unique creative name. offerIdYes string Parent offer ID. channelIdYes string Target channel ID. placementIdNo string | null Placement within the channel. Default null. statusNo enum draft (default), active, paused, archived.templateTypeNo string Template format. Default "email_html". contentNo object Template content (subject, body, image URLs, etc.). personalizationNo array Personalization token mappings. Max 500 items. constraintsNo object Delivery constraints (time-of-day, frequency). abTestVariantNo string | null A/B test variant label. weightNo integer (0-100) Traffic weight for multi-variant rotation. Default 100. metricsNo object Performance 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, version: 1, and deletedAt: null. An audit log entry is created with a create action.
Error codes Code Reason 400Validation error (missing offerId, channelId, or name). 401Missing or invalid API key / session. 403Insufficient role (requires editor or admin). 409A creative with that name already exists. 415Content-Type is not application/json.
Update a creative 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 idYes 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 400Validation error. 401Missing or invalid API key / session. 403Insufficient role. 409A 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 idYes string Creative ID to delete.
Response 200 { "success" : true , "id" : "cre_abc123" }
Error codes Code Reason 400Missing id query parameter, entity not found, or entity already deleted. 401Missing or invalid API key / session. 403Insufficient role.
To restore a soft-deleted creative, use POST /api/v1/restore?entityType=creative&id={creativeId} (admin only).
Role requirements Method Minimum role GET viewerPOST editorPUT editorDELETE editor
Creatives Learn more about creating and managing creatives in the platform UI.
