Decision Flows API

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

Decision Flows list view in the Kaireon Studio — The Decision Flows page.

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 `50`, max `100`.
`cursor`	No	string	Cursor for keyset pagination (an `id`; returns rows with `id` less than the cursor).
`includeDeleted`	No	boolean	When `true`, includes soft-deleted flows.

If the tenant has zero Decision Flows, this endpoint lazily auto-creates a base flow and returns it, so the list is never empty for an active tenant.

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": {
    "limit": 50,
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

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.
`skipContactPolicy`	No	boolean	Opt out of implicit Contact Policy. Default `false` — the engine auto-applies global Contact Policy rules (DNC, frequency caps, cooldowns) when the flow has no explicit `contact_policy` node. Set `true` only for flows that must bypass safety rails (transactional, OTP, etc.).
`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 is not a settable request field on create — it is stripped by the validation schema. The first flow created in a tenant is automatically marked default; subsequent flows are created with isDefault: false.

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).
`403`	Insufficient role (requires `editor` or `admin`).
`409`	A Decision Flow with that key already exists.
`413`	Request body exceeds the 2 MB limit.
`415`	`Content-Type` is not `application/json`.
`422`	The provided `draftConfig` failed schema or pipeline validation (e.g. a `rank` and a `group` node in the same flow).
`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 decisioning gates
	`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

rank and group are mutually exclusive. A flow may contain a rank node (single-placement top-N selection) or a group node (multi-placement allocation across zones), but not both — rank throttles group’s input and leaves placements unfilled. A draftConfig containing both fails structural validation with RANK_AND_GROUP_CONFLICT and the create/update request is rejected with 422.

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.
`401`	Missing or invalid auth.
`403`	Insufficient role (requires `editor` or `admin`).
`404`	No Decision Flow with that `id` in your tenant.

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
}

Four-eyes publish approval (opt-in)

When the tenant setting requirePublishApproval is true, publish is gated: the flow must have a fresh, approved ApprovalRequest with entityType: "decisionFlow", action: "publish", and entityId equal to the flow’s id. Because approval-stage walking already rejects self-approval and duplicate approvers, an approved request implies two distinct identities. One approval authorizes exactly one publish: the successful publish stamps the approval’s approvalId onto the publishedVersions[] entry it creates, so a second publish on the same approval is rejected as consumed. The next publish needs a new approval. The gate fails closed — if the tenant-settings lookup errors, publish is blocked unless a valid approval already exists. The default (requirePublishApproval: false) keeps one-click publish for existing tenants. A blocked publish returns 422 and writes a publish_blocked audit entry:

{
  "title": "Publish approval required",
  "detail": "This tenant requires four-eyes approval before publishing decision flows. ...",
  "reason": "no_approval"
}

reason is "no_approval" (no fresh approved request) or "consumed" (the most recent approval was already used by a previous publish). The audit reason is publish_approval_missing or publish_approval_consumed respectively.

Error codes

Code	Reason
`404`	Decision Flow not found.
`409`	Concurrent modification detected. Retry.
`422`	The draft has no scoring config (a `scoring.method` for a V1 draft, or a non-empty `nodes` array for a V2 draft), or the opt-in fairness hard gate detected a disparate-impact breach over the last 7 days of traces, or four-eyes publish approval is required and missing/consumed (see above).

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:

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.

​Base path

​List Decision Flows

​Query parameters

​Response 200

​Get a single Decision Flow

​Path parameters

​Response 200

​Error codes

​Roles

​Create a Decision Flow

​Request body

​Example request

​Response 201

​Error codes

​Update a Decision Flow

​Request body

​Flow config v2 schema

​Pipeline node types

​Score node methods

​Rank node methods

​Compute node

​Example request

​Response 200

​Error codes

​Delete a Decision Flow

​Query parameters

​Response 200

​Error codes

​Publish a Decision Flow

​Request body

​Example request

​Response 200

​Four-eyes publish approval (opt-in)

​Error codes

​Role requirements

​Optimistic concurrency

​Soft-delete and audit

Decision Flows

Base path

List Decision Flows

Query parameters

Response `200`

Get a single Decision Flow

Path parameters

Response `200`

Error codes

Roles

Create a Decision Flow

Request body

Example request

Response `201`

Error codes

Update a Decision Flow

Request body

Flow config v2 schema

Pipeline node types

Score node methods

Rank node methods

Compute node

Example request

Response `200`

Error codes

Delete a Decision Flow

Query parameters

Response `200`

Error codes

Publish a Decision Flow

Request body

Example request

Response `200`

Four-eyes publish approval (opt-in)

Error codes

Role requirements

Optimistic concurrency

Soft-delete and audit