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.
Decision Flows are the heart of KaireonAI’s decisioning engine. Each flow defines a composable pipeline of nodes (enrichment, qualification, scoring, ranking, filtering) that selects and ranks Offers for a given customer context.
Base path List Decision Flows GET /api/v1/decision-flows
Returns a paginated list of Decision Flows, ordered by status then by last update (newest first).
Query parameters Parameter Required Type Description limitNo integer Maximum results per page. Default 25. cursorNo string Cursor for keyset pagination.
Response 200 { "data" : [ { "id" : "df_001" , "tenantId" : "t_001" , "key" : "credit-card-nba" , "name" : "Credit Card NBA" , "description" : "Next-best-action flow for credit card offers." , "status" : "active" , "autoAssembly" : true , "draftConfig" : { "version" : 2 , "nodes" : [] }, "publishedVersions" : [ { "version" : 1 , "publishedAt" : "2026-03-12T10:00:00.000Z" , "notes" : "Initial publish" } ], "rowVersion" : 3 , "createdAt" : "2026-03-10T12:00:00.000Z" , "updatedAt" : "2026-03-14T15:00:00.000Z" } ], "pagination" : { "total" : 2 , "limit" : 25 , "hasMore" : false , "nextCursor" : null } }
Create a Decision Flow POST /api/v1/decision-flows
Creates a new Decision Flow with a default draft configuration.
Request body Field Required Type Description keyYes string (1-255) Unique machine-readable key (used in the Recommend API). nameYes string (1-255) Human-readable name. descriptionNo string Flow description. statusNo enum draft (default), active, paused, archived.autoAssemblyNo boolean Auto-assemble when offers/channels change. Default true.
Example request { "key" : "credit-card-nba" , "name" : "Credit Card NBA" , "description" : "Next-best-action flow for credit card offers." , "autoAssembly" : true }
Response 201 Returns the created Decision Flow. The draftConfig is populated with the default stage configuration and publishedVersions starts as an empty array.
Error codes Code Reason 400Validation error (missing key or name). 409A Decision Flow with that key already exists. 415Content-Type is not application/json.429Rate limit exceeded (500 requests / 60 s).
Update a Decision Flow PUT /api/v1/decision-flows
Updates an existing Decision Flow. When draftConfig is provided, it is validated against the pipeline schema and goes through the pipeline validator for structural correctness.
Request body Field Required Type Description idYes string Decision Flow ID to update. nameNo string Updated name. descriptionNo string Updated description. statusNo enum draft, active, paused, archived.autoAssemblyNo boolean Toggle auto-assembly. draftConfigNo object Updated pipeline configuration. rowVersionNo integer Optimistic concurrency control. If provided and it does not match the current rowVersion, the update is rejected with 409.
Always send rowVersion when updating draftConfig to prevent overwriting concurrent edits. On conflict, the API returns 409 with a message to refresh and retry.
FlowConfigV2 schema The draftConfig must conform to the FlowConfigV2 schema:
version: Must be 2.nodes: Array of pipeline nodes (minimum 2). Each node has id, type, and config.flowConfig: Optional flow-level configuration.
Pipeline node types 16 node types organized across 3 phases:
Phase Node Type Description Phase 1 (Narrow) inventoryLoad candidate offers from the catalog match_creativesMatch offers to creatives for the request channel enrichLoad customer data from schema tables qualifyEvaluate qualification rules contact_policyApply contact policy suppression rules filterGeneric filter node conditionalConditional branching based on expressions Phase 2 (Score/Rank) scoreScore candidates using PRIE formula optimizeMulti-objective portfolio optimization rankRank and select top candidates groupGroup candidates by placement or category Phase 3 (Output) computeEvaluate formula-based personalized values set_propertiesSet custom properties on candidates responseFormat the final response Cross-phase call_flowExecute a sub-flow inline extension_pointInject custom logic at pre_score, score_override, or post_rank hooks
Score node methods The Score node uses the PRIE formula (Propensity x Relevance x Impact x Emphasis). Scoring methods include:
priority_weighted — Uses offer priority and business valuepropensity — Uses a scoring model for the P factorformula — Custom formula-based scoring
Rank node methods Method Description topNSelect the top N candidates by score diversityEnsure category/channel diversity in results round_robinRotate across categories or channels explore_exploitBalance known-good offers with exploration
Compute node Supports formulaExtras for adding personalized computed values to the response. Each extra defines a key, formula, and outputType that are evaluated per candidate at decision time.
Example request { "id" : "df_001" , "draftConfig" : { "version" : 2 , "nodes" : [ { "id" : "n1" , "type" : "inventory" , "config" : { "scope" : "category" , "categoryIds" : [ "cat_01" ] } }, { "id" : "n2" , "type" : "qualify" , "config" : {} }, { "id" : "n3" , "type" : "score" , "config" : { "method" : "priority_weighted" } }, { "id" : "n4" , "type" : "rank" , "config" : { "method" : "topN" , "topN" : 5 } }, { "id" : "n5" , "type" : "response" , "config" : {} } ] }, "rowVersion" : 2 }
Response 200 Returns the updated Decision Flow. The rowVersion is incremented.
Error codes Code Reason 400Validation error on draftConfig. 404Decision Flow not found. 409rowVersion mismatch (concurrent edit) or key conflict.422Pipeline validation failed (structural errors).
Delete a Decision Flow DELETE /api/v1/decision-flows?id={flowId}
Soft-deletes a Decision Flow by ID. The record is marked as deleted but retained in the database for audit purposes.
Query parameters Parameter Required Type Description idYes string Decision Flow ID to delete.
Response 200 { "success" : true , "cascaded" : 0 }
The cascaded field indicates how many related records (if any) were also soft-deleted.
This endpoint uses soft-delete — the record is not physically removed. It is excluded from GET results by default. To include soft-deleted records, pass ?includeDeleted=true on the GET request.
Error codes Code Reason 400Missing id query parameter, or soft-delete failed.
Publish a Decision Flow POST /api/v1/decision-flows/publish
Snapshots the current draftConfig as a new published version. The flow status is set to active. A scoring method must be configured before publishing.
Request body Field Required Type Description idYes string Decision Flow ID to publish. notesNo string Release notes for this version.
Example request { "id" : "df_001" , "notes" : "Added propensity scoring stage" }
Response 200 Returns the updated Decision Flow with the new version appended to publishedVersions.
{ "id" : "df_001" , "status" : "active" , "publishedVersions" : [ { "version" : 1 , "publishedAt" : "2026-03-12T10:00:00.000Z" , "notes" : "Initial publish" , "configSnapshot" : {} }, { "version" : 2 , "publishedAt" : "2026-03-14T15:00:00.000Z" , "notes" : "Added propensity scoring stage" , "configSnapshot" : {} } ], "rowVersion" : 4 }
Error codes Code Reason 404Decision Flow not found. 409Concurrent modification detected. Retry. 422scoring.method is not configured in the draft.
Role requirements Method Minimum role GET viewerPOST (create) editorPUT editorDELETE editorPOST (publish) editor
Optimistic concurrency Decision Flows support optimistic concurrency control via the rowVersion field. When updating a flow:
Read the current rowVersion from the GET response.
Include rowVersion in your PUT request body.
If the server’s rowVersion does not match, the update is rejected with 409 Conflict and a message to refresh and retry.
On successful update, the rowVersion is automatically incremented.
This prevents concurrent editors from overwriting each other’s changes.
Soft-delete and audit Decision Flows use soft-delete with audit snapshots. When a flow is deleted:
The deletedAt timestamp is set (record is retained).
An audit snapshot is captured with the full state before deletion.
Updates also create audit snapshots via auditedUpdate, incrementing the rowVersion on each change. The first flow created in a tenant is automatically marked as the default (isDefault: true).
To include soft-deleted flows in GET responses, add ?includeDeleted=true to the query string.
Decision Flows Learn more about building Decision Flows in the platform UI.
