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
{
"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
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.
{
"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
- The target version’s
configSnapshot is looked up from the flow’s published version history.
- A new version is appended (e.g., version 6) with the restored configuration and rollback notes.
- The flow’s
draftConfig is replaced with the restored configuration.
- The flow’s
status is set to active.
- Entity caches (offers, qualification rules) are invalidated so the rolled-back configuration takes effect immediately.
- 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 |
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.
After a rollback, use the 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"). 
