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)

{
  "flowId": "df_001",
  "created": false
}

Response (201 — newly created)

{
  "flowId": "df_002",
  "created": true
}

Roles

admin, editor

---

GET /api/v1/decision-flows//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

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