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.
Base path
List 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
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 decisionFlowId). |
415 | Content-Type is not application/json. |
Update a flow route
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. |
Delete a flow route
DELETE /api/v1/flow-routes?id={routeId}
Query parameters
| Parameter | Required | Type | Description |
|---|
id | Yes | string | Flow route ID to delete. |
Response 204
Empty body on success.
Error codes
| Code | Reason |
|---|
400 | Missing id query parameter. |
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | admin |
