Version control API

API endpoints for managing flow versions, publishing to production, and restoring history snapshots

Base path

All version control endpoints are scoped to a specific flow:

/flow/:flowId/versions

All endpoints require JWT authentication.

Enable and disable version control

Version control is toggled through the main flow update endpoint, not a dedicated version endpoint.

PATCH /flow/:flowId

Enable

Set versionControlEnabled to true in the request body. The system creates a V 1.0 deployed version and a Staging working version, both containing the flow’s current nodes and edges.

{
  "versionControlEnabled": true
}

Disable

Set versionControlEnabled to false. Optionally include sourceVersionId to choose which version’s state is extracted back into the base flow. If omitted, the deployed version is used.

{
  "versionControlEnabled": false,
  "sourceVersionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Get deployed version

Retrieves the currently deployed (production) version with its full node and edge data.

GET /flow/:flowId/versions/deployed

Response

Returns null if version control is not enabled or no deployed version exists.

id · string

UUID of the deployed version.

flowId · string

UUID of the parent flow.

versionName · string

Display name of the version (for example, V 1.0).

currentHistoryId · string

UUID of the active history snapshot.

updatedBy · string

User ID of the last modifier.

isStaging · boolean

Whether this is a staging version.

isDeployed · boolean

Whether this is the production version.

nodes · array

Array of node objects in this version.

edges · array

Array of edge objects in this version.

createdAt · datetime

Timestamp when the version was created.

updatedAt · datetime

Timestamp when the version was last updated.

Create version

Creates a new version by copying nodes and edges from an existing source version.

POST /flow/:flowId/versions/create

Request body

versionName · string · required

Display name for the new version.

sourceVersionId · string · required

UUID of the version to copy nodes and edges from.

Response

success · boolean

Whether the version was created.

message · string

Human-readable status message.

newVersion · FlowVersionDetailDto

The created version with its full node and edge data. Same shape as the deployed version response.

Example

cURL

curl -X POST https://your-api.com/flow/{flowId}/versions/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "versionName": "Experiment A",
    "sourceVersionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Publish to production

Copies the current state of a source version into the deployed version and increments the production version number.

POST /flow/:flowId/versions/push-to-production

Request body

versionId · string · required

UUID of the version to publish. Cannot be the deployed version itself.

Response

success · boolean

Whether the deployment succeeded.

message · string

Human-readable status message.

deployedVersion · FlowVersionDetailDto

The updated deployed version with its full node and edge data.

Behavior

• Version control must be enabled on the flow
• The source version cannot be the deployed version
• The production version name is auto-incremented:
  • Same source as last publish: minor version increments (for example, V 1.0 to V 1.1)
  • Different source: major version increments, minor resets (for example, V 1.1 to V 2.0)
• A history snapshot labeled Published as V x.y is created on the source version

Example

cURL

curl -X POST https://your-api.com/flow/{flowId}/versions/push-to-production \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Rollback version

Restores a version to a previous history snapshot. Creates a new history entry with the restored snapshot’s nodes and edges — the original history is preserved.

POST /flow/:flowId/versions/rollback

Request body

versionId · string · required

UUID of the version to roll back.

historyId · string · required

UUID of the history snapshot to restore.

Response

success · boolean

Whether the rollback succeeded.

message · string

Human-readable status message.

newHistoryId · string

UUID of the newly created history entry.

version · FlowVersionSummaryDto

The updated version summary.

Example

cURL

curl -X POST https://your-api.com/flow/{flowId}/versions/rollback \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "historyId": "f6e5d4c3-b2a1-0987-fedc-ba9876543210"
  }'

List versions

Returns a paginated list of all versions for a flow.

GET /flow/:flowId/versions

Query parameters

page · number · default: "1"

Page number.

pageSize · number · default: "10"

Number of versions per page.

Response

data · FlowVersionSummaryDto[]

Array of version summaries, each containing:

• id — Version UUID
• versionName — Display name
• isStaging — Whether this is the staging version
• isDeployed — Whether this is the production version
• historyCount — Number of history snapshots
• updatedBy — User ID of last modifier
• createdAt / updatedAt — Timestamps

meta · object

Pagination metadata with total, page, pageSize, and totalPages.

Example

cURL

curl https://your-api.com/flow/{flowId}/versions?page=1&pageSize=10 \
  -H "Authorization: Bearer {token}"

List version history

Returns a paginated list of history snapshots for a specific version.

GET /flow/:flowId/versions/:versionId/history

Query parameters

page · number · default: "1"

Page number.

pageSize · number · default: "10"

Number of history entries per page.

Response

data · VersionHistoryEntryDto[]

Array of history entries, each containing:

• id — History snapshot UUID
• flowVersionId — Parent version UUID
• updatedBy — User ID who created this snapshot
• nodeCount — Number of nodes in this snapshot
• edgeCount — Number of edges in this snapshot
• isCurrent — Whether this is the version’s active snapshot
• versionName — Optional label (for example, Published as V 1.1)
• createdAt — Timestamp

meta · object

Pagination metadata with total, page, pageSize, and totalPages.

Example

cURL

curl https://your-api.com/flow/{flowId}/versions/{versionId}/history?page=1&pageSize=10 \
  -H "Authorization: Bearer {token}"

Errors

The version control endpoints return standard HTTP error codes with descriptive messages.

Status	Condition
400	sourceVersionId is missing when creating a version
400	Flow not found
400	Version control is not enabled on the flow
400	Attempting to publish the deployed version to itself
404	Version or history snapshot not found