> ## 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.

# Flow Routes API

> Create, update, list, and delete flow-to-placement routing rules that map channels and placements to decision flows.

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.

<Info>
  See the [Decision Flows feature page](/decisioning/decision-flows) for details on how flow routes integrate with the decisioning pipeline.
</Info>

## 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`

```json theme={null}
[
  {
    "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`.              |

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

### Example request

```json theme={null}
{
  "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`

```json theme={null}
{
  "success": true,
  "cascaded": 0
}
```

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

<Note>
  This endpoint uses **soft-delete**. The record is marked as deleted but retained in the database.
</Note>

### 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`      |