Flow Routes API

Flow routes define which decision flow should be executed for a given channel and placement combination. When a Recommend API call is made, the platform uses flow routes to determine the appropriate decision flow based on the request’s channel and placement context.

See the Decision Flows feature page for details on how flow routes integrate with the decisioning pipeline.

Base path

/api/v1/flow-routes

List flow routes

GET /api/v1/flow-routes

Returns all flow routes for the current tenant, ordered by priority (highest first), then creation date (newest first). Each route is enriched with the associated decision flow’s name and key.

Response `200`

[
  {
    "id": "fr_001",
    "tenantId": "t_001",
    "channelId": "ch_email",
    "placementId": null,
    "decisionFlowId": "df_001",
    "priority": 10,
    "createdAt": "2026-03-10T12:00:00.000Z",
    "updatedAt": "2026-03-12T09:30:00.000Z",
    "decisionFlow": {
      "id": "df_001",
      "name": "Email NBA Pipeline",
      "key": "email-nba"
    }
  }
]

Create a flow route

POST /api/v1/flow-routes

Creates or updates a flow route (upsert). The unique key is the combination of tenantId, channelId, and placementId. If a route with the same channel/placement pair exists, it is updated.

Request body

Field	Required	Type	Description
`decisionFlowId`	Yes	string	The decision flow to route to.
`channelId`	No	string \| null	Channel ID to match. `null` matches any channel. Default `null`.
`placementId`	No	string \| null	Placement ID to match. `null` matches any placement. Default `null`.
`priority`	No	integer (>= 0)	Route priority (higher = evaluated first). Default `0`.

Setting both channelId and placementId to null creates a catch-all route that matches any request without a more specific route.

Example request

{
  "decisionFlowId": "df_001",
  "channelId": "ch_email",
  "placementId": null,
  "priority": 10
}

Response `201`

Returns the created or updated flow route object.

Error codes

Code	Reason
`400`	Validation error (missing/invalid `decisionFlowId`), or a referenced `decisionFlowId`, `channelId`, or `placementId` does not belong to the caller’s tenant.
`409`	A flow route for this channel + placement combination already exists (raised only on a concurrent-create race; the normal path upserts).
`415`	`Content-Type` is not `application/json`.

Update a flow route

PUT /api/v1/flow-routes

Updates an existing flow route by ID. Only provided fields are changed.

Request body

Field	Required	Type	Description
`id`	Yes	string	The flow route ID to update.
`decisionFlowId`	No	string	Updated decision flow ID.
`priority`	No	integer (>= 0)	Updated priority.

Response `200`

Returns the updated flow route object.

Error codes

Code	Reason
`400`	Validation error (missing `id`).
`404`	Flow route not found for this tenant (unknown or stale `id`).
`415`	`Content-Type` is not `application/json`.

Delete a flow route

DELETE /api/v1/flow-routes?id={routeId}

Deletes a flow route by ID.

Query parameters

Parameter	Required	Type	Description
`id`	Yes	string	Flow route ID to delete.

Response `200`

{
  "success": true,
  "cascaded": 0
}

Field	Type	Description
`success`	boolean	Always `true` on success
`cascaded`	integer	Number of related entities soft-deleted via cascade

This endpoint uses soft-delete. The record is marked as deleted but retained in the database.

Error codes

Code	Reason
`400`	Missing `id` query parameter, or soft-delete failed.
`404`	Flow route not found for this tenant.

Role requirements

Method	Minimum role
GET	`viewer`
POST	`editor`
PUT	`editor`
DELETE	`admin`

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base path

List flow routes

Response `200`

Create a flow route

Request body

Example request

Response `201`

Error codes

Update a flow route

Request body

Response `200`

Error codes

Delete a flow route

Query parameters

Response `200`

Error codes

Role requirements

​Base path

​List flow routes

​Response 200

​Create a flow route

​Request body

​Example request

​Response 201

​Error codes

​Update a flow route

​Request body

​Response 200

​Error codes

​Delete a flow route

​Query parameters

​Response 200

​Error codes

​Role requirements

Base path

List flow routes

Response `200`

Create a flow route

Request body

Example request

Response `201`

Error codes

Update a flow route

Request body

Response `200`

Error codes

Delete a flow route

Query parameters

Response `200`

Error codes

Role requirements