> ## Documentation Index > Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/automations/{id}/versions openapi: 3.1.0 info: title: Eigenpal API version: 1.0.0 description: >- Public REST API for inspecting automations, starting and monitoring runs, managing files, collecting human reviews, and running evaluations. contact: name: Eigenpal url: https://eigenpal.com license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.eigenpal.com description: Production (canonical API hostname) security: - bearerAuth: [] tags: - name: Metadata description: Authenticate and inspect the current API context. - name: Automations description: >- Inspect runnable workflow and agent automations, their versions, triggers, and source sync state. - name: Runs description: >- Start, monitor, retry, review, and debug automation runs, including artifacts. - name: Reviews description: >- Record human review verdicts, manage corrected outputs, and monitor review health. - name: Files description: Upload reusable files for later run or dataset use. - name: Evaluation description: >- Manage datasets, examples, evaluators, experiment batches, evaluator scores, and run promotion workflows. paths: /v1/automations/{id}/versions: post: tags: - Automations summary: Create a workflow version description: >- 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. operationId: automations.versions.create parameters: - in: path name: id schema: type: string description: >- Workflow id, agent id, or typed alias like workflows.slug / agents.slug required: true description: >- Workflow id, agent id, or typed alias like workflows.slug / agents.slug requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAutomationVersionRequest' responses: '201': description: Created workflow version. content: application/json: schema: $ref: '#/components/schemas/AutomationVersion' '400': description: Validation error. Request shape did not match the spec. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '403': description: API key lacks required scope content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '409': description: Conflict. The resource is in a state that forbids the request. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '413': description: Payload too large. Upload exceeded the per-request size cap. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '429': description: Rate limit exceeded headers: Retry-After: description: Seconds until the next request may succeed schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' components: schemas: CreateAutomationVersionRequest: anyOf: - type: object properties: yaml: type: string minLength: 1 maxLength: 1048576 description: >- Validated workflow YAML to publish as a new tagged version. Mutually exclusive with `historyId`. At most 1 MiB. version: type: string pattern: ^\d+\.\d+\.\d+$ description: Bare semver tag such as 1.2.0. Do not include a leading v. activate: description: >- 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. type: boolean required: - yaml - version additionalProperties: false - type: object properties: historyId: type: string minLength: 1 description: >- Existing version id from GET /automations/{id}/versions. Creates a new tagged snapshot copied from that version; the source tag is left unchanged. Mutually exclusive with `yaml`. version: type: string pattern: ^\d+\.\d+\.\d+$ description: Bare semver tag such as 1.2.0. Do not include a leading v. activate: description: >- 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. type: boolean required: - historyId - version additionalProperties: false description: >- 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. AutomationVersion: type: object properties: id: type: string automationId: type: string version: anyOf: - type: string - type: 'null' sourceRef: anyOf: - type: string - type: 'null' isCurrent: type: boolean createdAt: anyOf: - type: string - type: string required: - id - automationId - version additionalProperties: false ApiErrorEnvelope: type: object properties: issues: type: array items: $ref: '#/components/schemas/ApiErrorIssue' requestId: type: string description: Request id echoed via the x-request-id header hint: description: Suggested fix for known error patterns type: string docsUrl: description: Link to relevant docs type: string conflictingWorkflowId: description: >- Present on 409 workflow_name_conflict responses. Id of the workflow that already owns the requested name. type: string required: - issues - requestId additionalProperties: false ApiErrorIssue: type: object properties: field: type: string description: JSON path of the offending field, or "" message: type: string description: Human-readable error message code: type: string description: >- Machine-readable error code (e.g. invalid_value, not_found, api_trigger_disabled, manual_trigger_disabled) severity: type: string enum: - error - warning description: Issue severity required: - field - message - code - severity additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key issued from Settings → API Keys. Pass as `Authorization: Bearer `. ````