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

{
  "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

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

---

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").

See also: Decision Flow Versions | Decision Flows | Change History