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

> Retrieve the published version history of a decision flow, or fetch the full configuration snapshot for a specific version.

## GET /api/v1/decision-flows/versions

Every time a decision flow is published, a versioned snapshot of its configuration is recorded. This endpoint lets you list all published versions for a flow or retrieve the full configuration for a specific version. Use it to audit configuration changes over time, compare versions, or inspect exactly what was live at a given point.

### Authentication

Requires a valid tenant and one of the following roles: **admin** or **editor**.

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

***

### List All Published Versions

Returns a summary list of all published versions for a decision flow. The full `configSnapshot` is omitted to keep the response lightweight -- use the single-version endpoint below to fetch the full config.

#### Query Parameters

| Parameter | Type   | Required | Description          |
| --------- | ------ | -------- | -------------------- |
| `id`      | string | Yes      | The decision flow ID |

#### Example Request

```bash theme={null}
curl -X GET "https://playground.kaireonai.com/api/v1/decision-flows/versions?id=flow_abc123" \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer sk_live_abc123"
```

#### Example Response

```json theme={null}
{
  "flowId": "flow_abc123",
  "versions": [
    {
      "version": 1,
      "publishedAt": "2026-03-10T09:00:00.000Z",
      "notes": "Initial publish",
      "summary": {
        "nodeCount": 5,
        "scoringMethod": "propensity"
      }
    },
    {
      "version": 2,
      "publishedAt": "2026-03-15T14:30:00.000Z",
      "notes": "Added enrichment stage for loyalty tier",
      "summary": {
        "nodeCount": 7,
        "scoringMethod": "propensity"
      }
    },
    {
      "version": 3,
      "publishedAt": "2026-03-20T11:15:00.000Z",
      "notes": "Switched to scorecard scoring",
      "summary": {
        "nodeCount": 7,
        "scoringMethod": "scorecard"
      }
    }
  ]
}
```

#### Response Fields

| Field                              | Type           | Description                                                                                                  |
| ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `flowId`                           | string         | The decision flow ID                                                                                         |
| `versions`                         | array          | List of version summaries, ordered by publish time                                                           |
| `versions[].version`               | integer        | Sequential version number                                                                                    |
| `versions[].publishedAt`           | string         | ISO 8601 timestamp of when the version was published                                                         |
| `versions[].notes`                 | string         | Human-readable notes provided at publish time                                                                |
| `versions[].summary.nodeCount`     | integer        | Number of nodes in the flow configuration (V2 format)                                                        |
| `versions[].summary.scoringMethod` | string or null | Scoring method used in the flow (e.g., `propensity`, `scorecard`, `priority_weighted`), or `null` if not set |

***

### Get a Specific Version

Returns the full configuration snapshot for a single published version, including the complete flow definition (nodes, edges, stages, scoring config).

#### Query Parameters

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| `id`      | string  | Yes      | The decision flow ID           |
| `version` | integer | Yes      | The version number to retrieve |

#### Example Request

```bash theme={null}
curl -X GET "https://playground.kaireonai.com/api/v1/decision-flows/versions?id=flow_abc123&version=2" \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer sk_live_abc123"
```

#### Example Response

```json theme={null}
{
  "flowId": "flow_abc123",
  "version": 2,
  "publishedAt": "2026-03-15T14:30:00.000Z",
  "notes": "Added enrichment stage for loyalty tier",
  "configSnapshot": {
    "nodes": [
      { "id": "enrich-1", "type": "enrich", "data": { "schemaId": "sch_customers", "fields": ["loyalty_tier", "lifetime_value"] } },
      { "id": "qualify-1", "type": "qualify", "data": { "rules": ["rule_active_customers"] } },
      { "id": "score-1", "type": "score", "data": { "method": "propensity", "modelKey": "model_bayesian_v3" } },
      { "id": "rank-1", "type": "rank", "data": { "limit": 5 } }
    ],
    "edges": [
      { "source": "enrich-1", "target": "qualify-1" },
      { "source": "qualify-1", "target": "score-1" },
      { "source": "score-1", "target": "rank-1" }
    ],
    "stages": {
      "scoring": { "method": "propensity", "modelKey": "model_bayesian_v3" }
    }
  }
}
```

#### Response Fields

| Field            | Type    | Description                                                                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowId`         | string  | The decision flow ID                                                                                                                        |
| `version`        | integer | Version number                                                                                                                              |
| `publishedAt`    | string  | ISO 8601 timestamp of when this version was published                                                                                       |
| `notes`          | string  | Notes provided at publish time                                                                                                              |
| `configSnapshot` | object  | The complete flow configuration as it existed at publish time. Includes `nodes`, `edges`, and `stages` depending on the flow format version |

***

## Error Responses

| Status | Cause                                                             |
| ------ | ----------------------------------------------------------------- |
| `400`  | Missing `id` query parameter, or `version` is not a valid integer |
| `401`  | Missing or invalid authentication credentials                     |
| `403`  | Insufficient role (requires admin or editor)                      |
| `404`  | Decision flow not found, or the specified version does not exist  |
| `500`  | Internal server error                                             |

***

<Tip>
  Use the version list to build a visual timeline of flow changes in your CI/CD dashboard. The `summary` object gives you a quick diff indicator (node count changed, scoring method changed) without downloading the full config.
</Tip>

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