Create a workflow version
Create a tagged YAML workflow candidate from validated YAML or by copying an existing snapshot (historyId). Provide exactly one of yaml or historyId. Copy creates a new tagged row and leaves the source tag unchanged; it does not retag the original. Defaults to making the new version current. Set activate: false to keep it off live traffic until promote — that path requires an existing current workflow version and returns 400 if HEAD is empty. Agent automations are Git-backed and return 400. Requires a Bearer API key or a dashboard session.
Authorizations
API key issued from Settings → API Keys. Pass as Authorization: Bearer <key>.
Path Parameters
Workflow id, agent id, or typed alias like workflows.slug / agents.slug
Body
- Option 1
- Option 2
Exactly one of yaml or historyId, plus a bare semver version. YAML is capped at 1 MiB. historyId copies the selected snapshot into a new tagged row and does not retag the source. Set activate: false to create a detached candidate that does not move live HEAD; that path requires an existing current version.
Validated workflow YAML to publish as a new tagged version. Mutually exclusive with historyId. At most 1 MiB.
1 - 1048576Bare semver tag such as 1.2.0. Do not include a leading v.
^\d+\.\d+\.\d+$Whether to make the new version current immediately. Defaults to true. Set false to keep a tagged candidate off live traffic until promote. activate: false requires an existing current workflow version and returns 400 if HEAD is empty.