> ## 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 Flow Internals

> Assembly log, base flow creation, and internal decision flow management endpoints.

## POST /api/v1/decision-flows/ensure-base

Ensures a default "Base NBA Flow" exists for the tenant. If one already exists, returns its ID without creating a new one. Useful during onboarding or when the tenant needs a guaranteed starting flow.

### Auto-created node order

The base flow ships with the following nodes (defined in `lib/decision-flows/base-flow.ts:buildBaseFlowConfig`):

| Phase      | Node              | Default config                                          |
| ---------- | ----------------- | ------------------------------------------------------- |
| 1 (Narrow) | `inventory`       | `scope: "all"`, `includeStatuses: ["active"]`           |
| 1 (Narrow) | `match_creatives` | `placementMatchMode: "exact"`, `requireCreative: false` |
| 1 (Narrow) | `enrich`          | optional schema lookup with `lookupKey: "customer_id"`  |
| 1 (Narrow) | `qualify`         | `mode: "all"`                                           |
| 1 (Narrow) | `contact_policy`  | `mode: "all"`                                           |
| 1 (Narrow) | `extension_point` | `pre_score` hook (unconfigured)                         |
| 2 (Score)  | `score`           | `method: "priority_weighted"`                           |
| 2 (Score)  | `extension_point` | `score_override` hook (unconfigured)                    |
| 2 (Score)  | `rank`            | `method: "diversity"`, `maxCandidates: 5`               |
| 3 (Output) | `extension_point` | `post_rank` hook (unconfigured)                         |
| 3 (Output) | `response`        | `responseFormat: "standard"`                            |

The `match_creatives` node with `placementMatchMode: "exact"` is a **no-op when the request does not specify a placement** (single-placement `placement` field or multi-placement `placements: [...]` body). When the request *does* specify a placement, the node filters candidates to creatives whose `placementId` matches, providing per-placement creative-pool isolation. `requireCreative: false` keeps offers that have no creative for the requested channel surfacing as fallback candidates so tenants who haven't yet bound creatives to placements aren't broken by the upgrade.

### Response (200 -- already exists)

```json theme={null}
{
  "flowId": "df_001",
  "created": false
}
```

### Response (201 -- newly created)

```json theme={null}
{
  "flowId": "df_002",
  "created": true
}
```

### Roles

admin, editor

***

## GET /api/v1/decision-flows/{id}/assembly-log

Returns the auto-assembly history for a decision flow. Each log entry records when the platform automatically rebuilt the flow's pipeline in response to entity changes (new offers, updated rules, etc.).

### Path Parameters

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `id`      | string | Decision flow ID |

### Response

```json theme={null}
{
  "decisionFlowId": "df_001",
  "autoAssembly": true,
  "entries": [
    {
      "timestamp": "2026-03-30T10:00:00Z",
      "trigger": "offer_created",
      "entityId": "off_005",
      "entityName": "Holiday Savings Promo",
      "pipelineVersion": 12,
      "nodesAdded": 2,
      "nodesRemoved": 0,
      "durationMs": 45
    },
    {
      "timestamp": "2026-03-29T15:30:00Z",
      "trigger": "qualification_rule_updated",
      "entityId": "qr_003",
      "entityName": "Min Credit Score",
      "pipelineVersion": 11,
      "nodesAdded": 0,
      "nodesRemoved": 0,
      "durationMs": 32
    }
  ],
  "count": 2
}
```

### Response Fields

| Field          | Type    | Description                                    |
| -------------- | ------- | ---------------------------------------------- |
| `autoAssembly` | boolean | Whether auto-assembly is enabled for this flow |
| `entries`      | array   | Assembly log entries (newest first)            |
| `count`        | integer | Total number of log entries                    |

### Error Codes

| Code  | Reason                  |
| ----- | ----------------------- |
| `404` | Decision flow not found |

### Roles

any authenticated

See also: [Decision Flows](/api-reference/decision-flows)