Flow versioning and publishing

Use flow versioning to keep an immutable record of a flow at a point in time, and to run one of those snapshots on demand.

How versioning works

When you edit a saved flow, you work on a draft. Click Save to write your changes to the flow’s saved definition and record a draft snapshot.

Publishing records an immutable version snapshot of the draft and marks it as the flow’s published version. Further edits create another draft.

Publishing does not gate what runs. Products, surfaces, schedules, and every other entry point that names the flow by ID execute the flow’s current saved definition, so a save reaches them immediately, whether or not you publish afterwards. A version snapshot runs only when a dispatch call pins it with options.flowVersionId.

Publish a flow

To publish a flow, follow these steps:

1. Make your changes in the editor.
2. Test the flow with representative inputs.
3. Click More save actions.
4. If you have unsaved changes, click Save & Publish. Otherwise, click Publish.

The published version is a snapshot you can identify in version history, load back into the editor, or run with options.flowVersionId. Saving is what changes the definition that Products run.

Version numbers

Runtype assigns an increasing number to each version snapshot. The interface displays labels such as v1 and v2. Saving can create a draft before you publish, so the first published version does not necessarily use v1.

Version entries can include a label, notes, a step summary, and a creation time.

Draft and published versions

The following table compares draft and published versions:

What a test run executes

What runs depends on where you start the run:

• The editor’s test run executes the current editor state. When you have unsaved changes, it sends those steps with the run, so the run reflects your edits and also records a test version snapshot of what ran. When the editor has no unsaved changes, it runs the flow’s saved definition.
• The run_flow MCP tool, and a dispatch call that names a flow by ID without steps or a version pin, execute the flow’s saved definition. Neither runs a version snapshot, and run_flow does not accept a version pin.
• A dispatch call with options.flowVersionId executes that version’s stored snapshot, so later edits to the saved definition do not affect it. The version ID is also recorded alongside the run’s persisted step results.

A pinned run never falls back to the saved definition. If the version ID does not exist, the call returns 404, and if the pinned snapshot cannot run on the engine that honors the pin, the call returns 422 rather than running a different definition.

Because a passing editor test can reflect unsaved edits, save the flow before you rely on the result. Saving is also what makes the change live for Products and other unpinned entry points.

Test before you save and publish

Test in the editor before you save, because a save is live for Products and other unpinned entry points. Use the following checks:

1. Run the flow with representative inputs.
2. If the flow has conditional branches, test each branch.
3. Verify that the outputs are correct.
4. Test error cases.
5. Review the execution results.

The test uses the current editor state, including unsaved steps. Save and publish after the checks pass.

View version history

To view version history, follow these steps:

1. Open the flow.
2. Click More save actions.
3. Click View versions.

The Version History sheet lists version labels, status badges, step summaries, creation times, and notes when available. The current published version has a live badge.

Load or publish a previous version

To load an earlier version into the editor, follow these steps:

1. In the flow editor, click View versions.
2. Find the version that you want to load.
3. Click Load. The editor replaces its current flow name, description, and steps with the selected version.
4. Review and test the loaded version.

To publish the loaded version, click More save actions, then click Publish. When the loaded version differs from the saved flow, publishing first saves a new draft snapshot and then creates a published snapshot.

To publish a version straight from Version History, click Publish beside it. This loads the version into the editor, writes it back to the flow’s saved definition, and marks it as published, so Products and other unpinned entry points run it right away.

Loading a version, or publishing a version from Version History, discards unsaved editor changes. Save your changes first if you need them.

Publish from API, SDK, CLI, or MCP

Every stored-version publish surface performs the same atomic server operation: it validates and writes the snapshot’s name, description, and steps to the live Flow before promoting the version. Products, schedules, run_flow, and unpinned dispatches therefore run that snapshot immediately.

1
const result = await client.flowVersions.publish(flowId, versionId)
2
console.log(result.applied, result.warnings, result.lastModifiedSource)

A Flow managed by ensure rejects the write by default with 409 and code: "managed_by_code_conflict". After explicit confirmation, use the spelling for your client:

• REST and TypeScript SDK: onConflict: "overwrite"
• CLI: runtype flow-versions publish FLOW_ID --version VERSION_ID --overwrite-managed
• MCP: publish_flow_version with on_conflict: "overwrite"
• Code Mode: { onConflict: "overwrite" }

The response’s applied, warnings, and lastModifiedSource fields report what changed. Publishing also regenerates Product capability parameter schemas derived from the Flow.

Best practices

Use these practices to manage flow changes:

• Save small, incremental changes, and publish a version after each one so you have a snapshot to return to.
• Remember that saving is what changes live behavior. Test in the editor before you save, and try a change in a non-production Product before you save it on a flow that production traffic uses.
• Review execution logs after you save.
• To go back to an earlier definition, click Publish beside that version in Version History, or load it into the editor and save it.

Next steps

Continue with these flow guides:

• Creating and editing flows: create and test flows
• Debugging flows: investigate execution issues
• Manage Flows as code: keep flow definitions in your repository