Workflow version
Included from Basic tier
A workflow version is one stored, numbered body of a workflow: the YAML
source and compiled step list as they stood when that version was saved.
Runs always execute a specific version, so the history is what makes old runs
explainable. JSON:API type: workflow_version.
The v2 OpenAPI document declares this resource's schema; the resource-field coverage gate holds this page to it.
Endpoints
| Route | Serves |
|---|---|
GET /api/projects/{project}/workflows/{code}/versions | List, version ascending (the model's default scope). Meta carries update/delete authorisations on the workflow's path. |
GET …/versions/{version} | Show, by version number; a non-integer or unknown number is a 404. |
PATCH/PUT …/versions/{version} | Upsert/update a version (the workflow write surface). |
GET …/versions/{version}/runs | The runs of that exact version. |
When a run is created naming a version number, that exact row is used — drafts included; naming no version selects the latest published (non-draft, highest number) version.
Attributes
| Attribute | Type | Meaning / origin / null semantics |
|---|---|---|
code | string | The owning workflow's code (denormalised onto every version). |
name | string | The owning workflow's display name. |
description | string/null | The owning workflow's description; null when unset. |
draft | boolean | Unpublished. A draft is runnable only by naming its number explicitly, is excluded from latest_published_version, and is what the draft-only destroy variant removes. |
archived | boolean | The version is archived. |
created_by | string | Username of the version's creator. |
created_at / updated_at | string | Version row timestamps. |
source_yaml | string | This version's YAML source, verbatim. |
steps | array | This version's compiled step list. The step grammar carries the orchestration fields — when:, for_each:/as:/run_as:, retries:, with: (typed-input supply to the nested run) and on_error: (string fail/continue, or the object handler form on single-target change steps) — plus, on a change step targeting a project or environment node, the git-identity fields git_remote_name:/git_rev: (optional; default: the target project's sole configured remote, HEAD — the child is a discovered git-remote change) — as served by GET /api/ui_support/json_schema?model_name=workflow (and byte-identically by the v2 WorkflowService.GetWorkflowSchema). |
resolved_steps | array | Always [] on plain reads (virtual; populated upstream only by the opt-in ?resolved_steps validation run). |
sample_properties | object | Sample properties stored with the version; {} when none. |
inputs | object | This version's typed run-input declarations: name → {type, values, default, required, description}. {} when the version declares none. Validated at publish (types, enum values, default scope — defaults are literals or expressions over run.* only); what the GUI run form renders and run creation validates supplied values against. |
version | integer | The version number — the show URL's identity and the list's sort key. |
Lock/publish semantics
A workflow version has no locked attribute (that belongs to
template_version). Its publication state is the draft boolean: saving a
new body creates the next numbered version, and publishing flips draft to
false, after which that number is immutable history — later edits land as a
new version. archived retires a version without deleting its history.
Relationships, links and includes
| Relationship | Target type | Notes |
|---|---|---|
parent | project | The owning project (related link /api/projects/{project}). |
Links: self
(/api/projects/{project}/workflows/{code}/versions/{version}), runs
(that version's runs), workflow (the owning definition). Workflow versions
are also includable from other resources (workflow_run's default
include=workflow_version, a workflow's include=versions).
The v2 service — WorkflowService versions lane
ListWorkflowVersions serves the versions newest first (the order the
GUI's editor loads the latest from), GetWorkflowVersion one version,
UpdateWorkflowVersion the authoring upsert (save, validate_flag,
resolve_properties + property_overrides_json, publish via
draft: false), DeleteWorkflowVersion one version and
DeleteWorkflowDraftVersions the draft prune. See
opschain docs api-v2.
Related pages
opschain docs resources/workflow— the owning definition (and the latest-version denormalisation it serves).opschain docs resources/workflow_run— executions of a version.