> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create workflow version

> Save a draft and explain its changes in Markdown.

## 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`.