Decision Flows are the heart of KaireonAI’s decisioning engine. Each flow defines a pipeline of stages (enrichment, qualification, scoring, ranking, filtering) that selects and ranks Offers for a given customer context. Flows support both the Fixed-Stage Pipeline (v1) and the Composable Pipeline (v2).
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 appropriate schema (v1 Fixed-Stage Pipeline or v2 Composable Pipeline, auto-detected). V2 configs also go 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 (v1 or v2). 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.
Example request { "id" : "df_001" , "draftConfig" : { "version" : 2 , "nodes" : [ { "id" : "n1" , "type" : "candidate_source" , "config" : { "categoryIds" : [ "cat_01" ] } }, { "id" : "n2" , "type" : "qualify" , "config" : {} }, { "id" : "n3" , "type" : "score" , "config" : { "method" : "priority" } }, { "id" : "n4" , "type" : "rank" , "config" : { "topN" : 5 } }, { "id" : "n5" , "type" : "output" , "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 (v2 structural errors).
Delete a Decision Flow DELETE /api/v1/decision-flows?id={flowId}
Deletes a Decision Flow by ID.
Query parameters Parameter Required Type Description idYes string Decision Flow ID to delete.
Response 204 Empty body on success.
Error codes Code Reason 400Missing id query parameter.
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
Decision Flows Learn more about building Decision Flows in the platform UI.
