Versioning

Every published workflow has a monotonically increasing version counter. Each version is an immutable snapshot - running instances are immune to edits even while the canvas is being modified.

Version lifecycle

Publishing also deploys the validated definition YAML to the execution layer automatically - there is no separate deploy click for the common path.

Creating a version snapshot

A new snapshot is created automatically on every saved change through the workflow update API - edits, publishes, and archives alike (publish is not special-cased). Each snapshot stores:

Field	Description
`version`	Monotonically increasing integer
`nodes`	Canvas node definitions JSON
`edges`	Canvas edge definitions JSON
`viewport`	Canvas viewport (pan/zoom)
`definitionYaml`	The validated workflow definition YAML
`definitionVersion`	Schema version (`v1.1` or `v2`)
`triggerConfig`	Trigger configuration snapshot
`providerRequirements`	Required provider declarations
`workflowConfig`	Top-level workflow config
`schemaHash`	SHA-256 of the definition YAML for integrity checks
`changedBy`	User or system identity that created the snapshot
`changeReason`	Optional free-text description
`createdAt`	UTC timestamp

Snapshots are immutable - they are never modified after creation.

Version API

GET /api/workflows/{workflowId}/versions
Authorization: Bearer rsk_live_...

Returns an array of version summaries ordered newest-first:

[
  {
    "version": 5,
    "changedBy": "user_abc",
    "changeReason": "Add QA gate timeout",
    "createdAt": "2026-06-01T10:30:00Z",
    "schemaHash": "a3f8..."
  },
  ...
]

GET /api/workflows/{workflowId}/versions/{version}/diff?compare={fromVersion}
Authorization: Bearer rsk_live_...

Returns a VersionDiff comparing this version to compare. The compare query parameter is required (400 without it):

{
  "fromVersion": 4,
  "toVersion": 5,
  "nodesAdded": ["qa-gate"],
  "nodesRemoved": [],
  "nodesModified": ["dispatch-development"],
  "edgesAdded": 2,
  "edgesRemoved": 1,
  "yamlChanged": true
}

POST /api/workflows/{workflowId}/versions/{version}/rollback
Authorization: Bearer rsk_live_...

Restores the canvas to the state captured in the specified snapshot. The current draft is replaced. This creates a new version snapshot of the restored state so the rollback itself is tracked in the audit history.

Publishing

There is no dedicated publish endpoint. Publishing is a status transition on the workflow update API:

PATCH /api/workflows/{workflowId}
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "status": "published"
}

Publish authorization is enforced separately from edit authorization (a user who can edit may still be denied publish). On publish the platform validates the definition, snapshots a version, and deploys the YAML to the execution layer.

Note that workflows do not have a draft-vs-live split: edits to a published workflow apply to the live definition (each save is version-snapshotted, so you can always roll back). A draft-always editing model with a diff-vs-live review panel exists for admin-managed workflow templates - see Template Subscriptions - not for project workflows.

Running instances and versioning

Running workflow instances are pinned to the version that was published when they started. If you publish v5 while instance I-42 is mid-execution (was started on v4), instance I-42 continues to completion on v4's definition. Only new triggers start on v5.

This guarantee holds for:

Suspended instances waiting for a gate signal
Instances mid-loop (see Runtime: Loops)
Instances paused via the pause/resume API

Audit trail

Every version creation emits an audit event (workflow.version_created) with the workflow ID, version number, user identity, and change reason. Audit events feed the organisation's hash-chain audit log. See Audit Trail.

Publish and Deploy - the full draft → publish → deploy flow
Validation - checks that run before a version snapshot is created
Runtime: Gates - how instances stay pinned to their version