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

> Roll back a decision flow to a previously published version. Creates a new version with the restored configuration, preserving immutable history.

## POST /api/v1/decision-flows/rollback

Restores a decision flow to a previously published version. Instead of overwriting history, rollback creates a **new version** that contains the configuration from the target version. This means the version history is fully immutable -- you can always see when a rollback happened and what it restored.

For example, if a flow is currently at version 5 and you roll back to version 3, the system creates version 6 whose configuration matches version 3. Versions 4 and 5 remain in the history for auditing.

### Authentication

Requires a valid tenant and the **admin** role.

| Header          | Required | Description             |
| --------------- | -------- | ----------------------- |
| `X-Tenant-Id`   | Yes      | Tenant identifier       |
| `Authorization` | Yes      | Bearer token or API key |

***

### Request Body

```json theme={null}
{
  "id": "flow_abc123",
  "version": 3,
  "notes": "Reverting due to scoring regression in v5"
}
```

| Field     | Type    | Required | Description                                                                                                     |
| --------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `id`      | string  | Yes      | The decision flow ID to roll back                                                                               |
| `version` | integer | Yes      | The target version number to restore. Must be an existing published version with a valid configuration snapshot |
| `notes`   | string  | No       | Optional explanation for the rollback. Prepended with `"Rollback to vN: "` in the version history               |

***

### Example Request

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/decision-flows/rollback \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer sk_live_abc123" \
  -d '{
    "id": "flow_abc123",
    "version": 3,
    "notes": "Reverting due to scoring regression in v5"
  }'
```

### Example Response

The response returns the full updated decision flow record, including the new version in `publishedVersions`.

```json theme={null}
{
  "id": "flow_abc123",
  "tenantId": "my-tenant",
  "name": "Default Recommendation Flow",
  "key": "default-flow",
  "status": "active",
  "draftConfig": {
    "nodes": [ ... ],
    "edges": [ ... ],
    "stages": {
      "scoring": { "method": "propensity", "modelKey": "model_bayesian_v3" }
    }
  },
  "publishedVersions": [
    {
      "version": 1,
      "publishedAt": "2026-03-10T09:00:00.000Z",
      "notes": "Initial publish"
    },
    {
      "version": 2,
      "publishedAt": "2026-03-15T14:30:00.000Z",
      "notes": "Added enrichment stage"
    },
    {
      "version": 3,
      "publishedAt": "2026-03-20T11:15:00.000Z",
      "notes": "Switched to scorecard scoring"
    },
    {
      "version": 4,
      "publishedAt": "2026-03-22T08:00:00.000Z",
      "notes": "New qualification rules"
    },
    {
      "version": 5,
      "publishedAt": "2026-03-25T16:45:00.000Z",
      "notes": "Experimental propensity model"
    },
    {
      "version": 6,
      "publishedAt": "2026-04-01T10:30:00.000Z",
      "notes": "Rollback to v3: Reverting due to scoring regression in v5",
      "configSnapshot": { "..." : "..." }
    }
  ],
  "rowVersion": 7,
  "createdAt": "2026-03-10T08:00:00.000Z",
  "updatedAt": "2026-04-01T10:30:00.000Z"
}
```

***

### What Happens on Rollback

1. The target version's `configSnapshot` is looked up from the flow's published version history.
2. A **new version** is appended (e.g., version 6) with the restored configuration and rollback notes.
3. The flow's `draftConfig` is replaced with the restored configuration.
4. The flow's `status` is set to `active`.
5. Entity caches (offers, qualification rules) are invalidated so the rolled-back configuration takes effect immediately.
6. An audit log entry is recorded with the rollback details, including the source and target version numbers.

### Optimistic Concurrency

The rollback uses `rowVersion`-based optimistic concurrency control. If another user modifies the same flow between your read and the rollback, the request returns a `409 Conflict` and you should retry.

***

## Error Responses

| Status | Cause                                                                                     |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | Missing `id` (must be a string) or missing `version` (must be a number)                   |
| `401`  | Missing or invalid authentication credentials                                             |
| `403`  | Insufficient role (requires admin)                                                        |
| `404`  | Decision flow not found, or the specified version does not exist in the published history |
| `409`  | Concurrent modification detected -- another user updated the flow. Retry the request      |
| `500`  | Internal server error                                                                     |

***

<Warning>
  Rollback replaces the current draft configuration with the restored version. Any unpublished draft changes will be overwritten. If you need to preserve in-progress work, publish or export the current draft before rolling back.
</Warning>

<Tip>
  After a rollback, use the [Decision Flow Versions](/api-reference/decision-flow-versions) endpoint to confirm the new version was created correctly. The version notes will clearly indicate it was a rollback (e.g., `"Rollback to v3: Reverting due to scoring regression in v5"`).
</Tip>

See also: [Decision Flow Versions](/api-reference/decision-flow-versions) | [Decision Flows](/api-reference/decision-flows) | [Change History](/api-reference/change-history)