Flow versioning and publishing

Use flow versioning to keep an immutable record of a flow at a point in time, to roll back to an earlier definition, 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 version 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 the current draft 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. 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.

Publishing an older version from Version History or the API is different. It writes that version back to the saved definition, so it also changes what unpinned entry points run.

Version types

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.

Each version has a type. The following table lists the types and where each one comes from:

Every version is immutable, and you can load or publish any version, whatever its type. A replaced published version stays in version history with the draft badge.

To record a labeled snapshot when you run a saved flow, pass these options to dispatch. When the request names the flow by ID without steps, the snapshot records the saved definition. When the request includes steps, the snapshot records those steps instead.

{
  "options": {
    "createVersion": true,
    "versionType": "draft",
    "versionLabel": "before-prompt-change",
    "versionNotes": "Snapshot before the summary prompt rewrite."
  }
}

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. The editor test uses the current editor state, including unsaved steps. 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.

Publish a flow

To publish a flow, follow these steps:

1. Make your changes in the editor.
2. Complete the checks in Test before you save and publish.
3. Click Save options, the arrow beside the save button, and then click Save & publish. If your changes are already saved, the item reads Publish to live.

The primary button shows Published only when the published version matches your saved flow. If saving succeeds but publishing fails, an inline View versions action lets you choose the saved version to publish without including newer edits.

To publish from the primary button, click Save options and turn on Publish on save. With this setting on, Save version only in the menu saves without publishing. The setting is off by default. Runtype remembers it for this flow in this browser, and changing it does not save or publish.

Publishing requires the FLOWS:WRITE permission. An API key without it gets a 403 response. For more information, see Permissions.

View version history

To view version history, follow these steps:

1. Open the flow.
2. Click Save options.
3. Click View versions.

The Version History sheet lists each version’s label, type badge, and creation time. It also shows a step summary, or the notes when a version has no step summary.

Load or publish a previous version

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

1. In the flow editor, click Save options, and then 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 Save options, and then click Save & publish. If the loaded version already matches the saved flow, click Publish to live instead. 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. 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.

On Enterprise plans, the audit trail shows who published each version and when. Each publish records a flow.published entry with the published configuration and a flow.active_version_changed entry with the previous and new version IDs.

What each entry point runs

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. If the dispatch can’t run the pinned snapshot’s steps, the call returns 422 rather than running a different definition. For the step configurations that a dispatch can’t run, see Flow validation warnings.

Versions created from code

When a dispatch call in upsert mode (flowMode: "upsert"), such as an SDK upsert, changes a flow’s steps, Runtype records a snapshot of the previous definition labeled Pre-upsert snapshot. Its notes summarize the change. Runtype records this snapshot as the flow’s published version, so it shows the live badge until you publish another version. The flow’s saved definition, which unpinned entry points run, holds the new steps. An upsert that creates a flow records its first published version, labeled v1, with the new steps.

After an upsert creates or changes a flow, the flow counts as managed in code and shows the Managed in code badge. Publishing a stored version over it needs confirmation, as described in Publish a stored version.

Because the snapshot is marked as live, its Publish button in Version History is unavailable. To roll back an upsert, click Load beside the snapshot. Then click Save options, and then click Save & publish. You can also publish the snapshot’s version ID from the API with the overwrite option. To turn off these snapshots, set upsertOptions.createVersionOnChange to false in the dispatch options.

For flows that you deploy with ensure, see Manage flows as code.

Publish from the API, SDK, CLI, or MCP

You can publish the current draft or a specific stored version outside the dashboard.

Find a version ID

To find a version ID, list the flow’s versions:

• REST: GET /v1/flow-versions/FLOW_ID. Add ?type=published, draft, test, or virtual to filter by type.
• TypeScript SDK: client.flowVersions.list('FLOW_ID')
• CLI: runtype flow-versions list FLOW_ID
• MCP: list_flow_versions

The response includes publishedVersionId and, for each version, its id, versionNumber, versionType, label, notes, stepSummary, stepCount, and createdAt.

To get one version, use GET /v1/flow-versions/FLOW_ID/VERSION_ID, client.flowVersions.get, runtype flow-versions get, or the get_flow_version MCP tool. To get the published version, use GET /v1/flow-versions/FLOW_ID/published, client.flowVersions.getPublished, runtype flow-versions published, or the get_published_flow_version MCP tool.

Publish the current draft

To publish the flow’s current draft, which is the same as Publish to live in the editor, call POST /v1/flows/FLOW_ID/publish:

import { RuntypeClient } from '@runtypelabs/sdk'
const client = new RuntypeClient({ apiKey: process.env.RUNTYPE_API_KEY })
const { publishedVersionId } = await client.flows.publish('FLOW_ID')

This creates a published snapshot of the draft. It doesn’t change the saved definition.

Publish a stored version

To publish a specific version, call POST /v1/flow-versions/FLOW_ID/publish with the version ID in the body:

{ "versionId": "VERSION_ID" }

The following samples publish a stored version from the SDK and the CLI:

const result = await client.flowVersions.publish('FLOW_ID', 'VERSION_ID')
console.log(result.applied, result.warnings, result.lastModifiedSource)

runtype flow-versions publish FLOW_ID --version VERSION_ID

Replace the following placeholders:

• FLOW_ID: the ID of the flow.
• VERSION_ID: the ID of the version, from Version History or Find a version ID.

Publishing a stored version from any of these clients has the same effect as clicking Publish in Version History. Runtype validates the version, writes its name, description, and steps to the saved flow, and marks it as published. Products, schedules, run_flow, and unpinned dispatches run that version immediately. Runtype also regenerates the parameter schemas of Product capabilities that use the flow. The response’s applied, warnings, and lastModifiedSource fields report what changed.

The call returns the following errors:

A flow whose last change came from code shows a Managed in code badge in the editor. The dashboard asks you to confirm before it publishes a version over it. To overwrite a code-managed flow from another client after you confirm the change, pass the overwrite option for your client:

• REST and TypeScript SDK: onConflict: "overwrite", for example client.flowVersions.publish('FLOW_ID', 'VERSION_ID', { 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" }

Best practices

Use these practices to manage flow changes:

• Save small, incremental changes. Each save records a draft snapshot that you can load or publish later from Version History.
• 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 guides:

• Creating and editing flows: create and test flows
• Debugging flows: investigate execution issues
• Manage flows as code: keep flow definitions in your repository
• Audit trail: see who published each version
• Execute a flow or agent: the dispatch reference, including options.flowVersionId