Skip to main content

​
Authentication & scope

Requires workflows-write and workspace admin access. Workflow Builder tokens additionally need active workspace agent access and the helper headers.

​
Change justification

Submit a valid definition, optional base_version_id, and change_notes in the same request. Notes are Markdown, limited to 20,000 characters. Explain the problem, changes and purpose; include a relevant Notion source link when used for the task. Notes are required for visible versions created through Workflow Builder, optional for human/ordinary API saves, and exempt for hidden debug snapshots. A supplied base must be a visible version of the same workflow. The new version is a draft; creating it does not publish it.

​
Response

201 returns the created version including its notes. Reusing an identical debug snapshot returns 200. Invalid definitions, missing agent justifications or foreign/debug base versions return 422; insufficient permissions return 403, and a workspace/workflow mismatch returns 404.