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.
Offers are the core decisioning entity in KaireonAI. Each offer represents a recommendation that can be scored, ranked, and delivered to a customer through one or more channels.
All offers 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 offers Returns a paginated list of offers for the current tenant, ordered by creation date (newest first). Each offer includes its creatives, category, and sub-category relations. By default, soft-deleted offers are excluded.
Query parameters Parameter Required Type Description limitNo integer Maximum number of results to return. Default 25. cursorNo string Cursor for keyset pagination. Pass the last id from the previous page. includeDeletedNo string Set to "true" to include soft-deleted offers in the results.
Response 200 { "data" : [ { "id" : "off_abc123" , "tenantId" : "t_001" , "name" : "Platinum Card Upgrade" , "status" : "active" , "categoryId" : "cat_01" , "subCategoryId" : "sub_01" , "category" : "acquisition" , "group" : "" , "priority" : 75 , "businessValue" : 50 , "mandatory" : false , "mandatoryReason" : null , "mandatoryExpiresAt" : null , "mandatoryApprovedBy" : null , "emergencyExcluded" : false , "description" : "Premium card upgrade offer for high-value customers." , "shortDesc" : "Upgrade to Platinum" , "eligibility" : {}, "budget" : { "maxPerDay" : 500 }, "schedule" : {}, "tags" : [ "credit-card" , "premium" ], "productType" : "credit_card" , "margin" : null , "revenueValue" : null , "metadata" : {}, "version" : 1 , "deletedAt" : null , "creatives" : [], "categoryRef" : { "id" : "cat_01" , "name" : "Acquisition" }, "subCategoryRef" : null , "createdAt" : "2026-03-10T12:00:00.000Z" , "updatedAt" : "2026-03-12T09:30:00.000Z" } ], "pagination" : { "total" : 42 , "limit" : 25 , "hasMore" : true , "nextCursor" : "off_xyz789" } }
Error codes Code Reason 401Missing or invalid API key / session. 403Insufficient role. 429Rate limit exceeded (2,000 requests / 60 s).
Create an offer Creates a new Offer. Triggers auto-assembly on any active Decision Flows.
Request body Field Required Type Description nameYes string (1-255) Unique offer name. statusNo enum draft (default), active, paused, archived.categoryIdNo string | null ID of the parent category. subCategoryIdNo string | null ID of the parent sub-category. categoryNo string Legacy category label. Default "engagement". groupNo string Legacy group label. Default "". priorityNo integer (0-100) Offer priority. Default 50. businessValueNo number (0-100) Business value score. Default 50. mandatoryNo boolean Mark as mandatory (admin-only). Default false. mandatoryReasonNo string | null Required when mandatory is true. mandatoryExpiresAtNo string | null ISO 8601 expiry. Required when mandatory is true. mandatoryApprovedByNo string | null Approver ID. Required when mandatory is true. emergencyExcludedNo boolean Emergency exclusion flag. Default false. descriptionNo string Full description. shortDescNo string Short description for cards/lists. eligibilityNo object Eligibility rule config. budgetNo object Budget constraints. scheduleNo object Scheduling config. tagsNo string[] Free-form tags. productTypeNo string Product type label (e.g., "credit_card", "loan"). Used by PRIE scoring for relevance matching. marginNo number Profit margin value. Feeds into the Impact (I) component of PRIE scoring. revenueValueNo number Expected revenue value. Feeds into the Impact (I) component of PRIE scoring. metadataNo object Arbitrary key-value metadata.
Setting mandatory to true requires the admin role and all three governance fields: mandatoryReason, mandatoryExpiresAt, and mandatoryApprovedBy.
Example request { "name" : "Platinum Card Upgrade" , "status" : "draft" , "categoryId" : "cat_01" , "priority" : 75 , "description" : "Premium card upgrade for high-value customers." , "tags" : [ "credit-card" , "premium" ], "budget" : { "maxPerDay" : 500 } }
Response 201 Returns the created offer object with all relations, version: 1, and deletedAt: null. An audit log entry is created with a create action.
Error codes Code Reason 400Validation error (missing name, invalid fields, mandatory fields missing). 401Missing or invalid API key / session. 403Non-admin trying to create mandatory offer. 409An offer with that name already exists. 415Content-Type is not application/json.
Update an offer Updates an existing offer. Only provided fields are changed. Triggers auto-assembly on status transitions. 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 offer ID to update.
Example request { "id" : "off_abc123" , "status" : "active" , "priority" : 90 }
Response 200 Returns the updated offer object with the incremented version.
Error codes Code Reason 400Validation error. 401Missing or invalid API key / session. 403Non-admin trying to set mandatory. 409Name conflict.
Delete an offer (soft-delete) DELETE /api/v1/offers?id={offerId}
Soft-deletes an offer by setting its deletedAt timestamp. Cascade behavior: all associated creatives are also soft-deleted. The version is incremented on the offer and each cascaded creative. An audit log entry is recorded for every affected entity.
Query parameters Parameter Required Type Description idYes string Offer ID to delete.
Response 200 { "success" : true , "id" : "off_abc123" , "cascaded" : 3 }
The cascaded field indicates how many child creatives were also soft-deleted.
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 offer, use POST /api/v1/restore?entityType=offer&id={offerId} (admin only). Restoring an offer does not automatically restore cascaded creatives — you must restore them individually.
Role requirements Method Minimum role GET viewerPOST editorPUT editorDELETE editor
Offers Learn more about creating and managing offers in the platform UI.
