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