Every time a workflow is saved, the new version gets a semantic version number, MAJOR.MINOR.PATCH. The number is based on how the version’s input and output schemas changed compared with the version it was saved from. You pin a run to a version or a range with workflow_version on Start a Run or in the SDKs.
What each bump means
A save takes the most severe bump of all the changes it contains. One major-level change makes the whole save a major bump.
What the version number does not cover
- Only top-level fields are compared. A change inside a nested object, such as a field added to or removed from an object-typed output, is versioned as a patch. So are changes to enums, formats, patterns and descriptions.
- An output changing from optional to required is versioned as a patch.
- The number describes the schema, not behavior. A patch can still change how the workflow navigates a site or which values it extracts.
- The bump is suggested automatically from the schema diff. The person saving the version can override it.
Pinning a run
Set at most one of these on a run. Without a pin, a run executes the latest version on the workflow’s default branch.
workflow_version accepts any range the semver package understands, including "^2.4.0", "~2.4.0", "2.4.x" and ">=2.4.0 <3.0.0". The highest matching version runs.
A range matches versions saved on any branch, not only the default branch. Version numbers are shared across all branches, so a version saved on an unmerged branch can be the highest match for your range.
Versions saved before semantic versioning
Workflows versioned before semantic versions were introduced had each version number N become N.0.0. A run pinned with the legacy workflow_version_number: N behaves like workflow_version: "N.x", so it also picks up later N.x.x versions.
Listing versions
Use List Versions or the SDKs (JavaScript, Python) to see each version’s number, branch and note. 
