Decision Flows API

Create, update, publish, and delete Decision Flows — the core decisioning pipelines.

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

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.

See the Decision Flows feature page and Composable Pipeline reference for UI guidance and architecture details.

Base path

/api/v1/decision-flows

---

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
limit	No	integer	Maximum results per page. Default 25.
cursor	No	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,
      "isDefault": true,
      "isProtected": false,
      "couplingOverride": null,
      "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
  }
}

---

Get a single Decision Flow

GET /api/v1/decision-flows/{id}

Returns one Decision Flow by ID for the authenticated tenant. Soft-deleted flows return 404.

Path parameters

Parameter	Required	Type	Description
id	Yes	string	Decision Flow ID.

Response 200

{
  "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"
}

Error codes

Code	Reason
401	Missing or invalid auth.
404	Flow not found, soft-deleted, or in another tenant.

Roles

admin, editor, viewer.

---

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
key	Yes	string (1-255)	Unique machine-readable key (used in the Recommend API).
name	Yes	string (1-255)	Human-readable name.
description	No	string	Flow description.
status	No	enum	draft (default), active, paused, archived.
autoAssembly	No	boolean	Auto-assemble when offers/channels change. Default true.
couplingOverride	No	"partial" | "atomic" | null	Per-flow override of the channel’s couplingMode. Resolution at decision time: flow.couplingOverride > channel.couplingMode > "partial". Use this when a single channel serves both atomic flows (e.g. email weekly digest) and partial flows (e.g. email transactional). null (default) defers to the channel.
draftConfig	No	object	Initial pipeline configuration (V2 schema). If omitted, the flow is created with a minimal default { version: 2, nodes: [], flowConfig: {} }. When provided it is validated structurally before write.
isDefault	No	boolean	When true, marks this flow as the tenant default and unsets isDefault on every other flow. The first flow in a tenant is auto-marked default regardless of this field.

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
400	Validation error (missing key or name).
409	A Decision Flow with that key already exists.
415	Content-Type is not application/json.
429	Rate 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
id	Yes	string	Decision Flow ID to update.
name	No	string	Updated name.
description	No	string	Updated description.
status	No	enum	draft, active, paused, archived.
autoAssembly	No	boolean	Toggle auto-assembly.
isProtected	No	boolean	Protected flows cannot be deleted (auto-set to true on publish).
isDefault	No	boolean	Mark this flow as the tenant default. Setting true unsets isDefault on every other flow in the tenant.
couplingOverride	No	"partial" | "atomic" | null	Per-flow override of the channel’s couplingMode. See create body table above for resolution order. Send null to clear the override and fall back to the channel’s mode.
draftConfig	No	object	Updated pipeline configuration.
rowVersion	No	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.

Flow config v2 schema

The draftConfig must conform to the flow config v2 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)	inventory	Load candidate offers from the catalog
	match_creatives	Match offers to creatives for the request channel
	enrich	Load customer data from schema tables
	qualify	Evaluate qualification rules
	contact_policy	Apply contact policy suppression rules
	filter	Generic filter node
	conditional	Conditional branching based on expressions
Phase 2 (Score/Rank)	score	Score candidates using PRIE formula
	optimize	Multi-objective portfolio optimization
	rank	Rank and select top candidates
	group	Group candidates by placement or category
Phase 3 (Output)	compute	Evaluate formula-based personalized values
	set_properties	Set custom properties on candidates
	response	Format the final response
Cross-phase	call_flow	Execute a sub-flow inline
	extension_point	Inject 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 value
• propensity — Uses a scoring model for the P factor
• formula — Custom formula-based scoring

Rank node methods

Method	Description
topN	Select the top N candidates by score
diversity	Ensure category/channel diversity in results
round_robin	Rotate across categories or channels
explore_exploit	Balance 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
400	Validation error on draftConfig.
404	Decision Flow not found.
409	rowVersion mismatch (concurrent edit) or key conflict.
422	Pipeline 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
id	Yes	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
400	Missing 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
id	Yes	string	Decision Flow ID to publish.
notes	No	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
404	Decision Flow not found.
409	Concurrent modification detected. Retry.
422	scoring.method is not configured in the draft.

---

Role requirements

Method	Minimum role
GET	viewer
POST (create)	editor
PUT	editor
DELETE	editor
POST (publish)	editor

---

Optimistic concurrency

Decision Flows support optimistic concurrency control via the rowVersion field. When updating a flow:

1. Read the current rowVersion from the GET response.
2. Include rowVersion in your PUT request body.
3. If the server’s rowVersion does not match, the update is rejected with 409 Conflict and a message to refresh and retry.
4. 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:

1. The deletedAt timestamp is set (record is retained).
2. 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.