Look up workflow version API endpoints

Use the following API endpoints to manage workflow versions, publish and unpublish workflows, restore previous versions, and validate definitions.

All endpoints use the base path /api/v1 and require a valid authorization token in the Authorization: Bearer header.

Version lifecycle endpoints

Method Path Description
GET /workflows/{workflow_id}/versions List all versions for a workflow
GET /workflows/{workflow_id}/versions/{version} Get a specific version by number
POST /workflows/{workflow_id}/versions/{version}/publish Publish a version
POST /workflows/{workflow_id}/unpublish Unpublish the current published version
POST /workflows/{workflow_id}/versions/{version}/restore Restore a previous version as a new draft
GET /workflows/{workflow_id}/versions/{version}/export Download a version as a JSON file
PATCH /workflows/{workflow_id}/versions/{version} Update a version's name or change description
POST /workflows/validate Validate a workflow definition without saving

Concurrent edit detection

The update (PATCH /workflows/{workflow_id}) and publish endpoints accept an optional expected_version field in the request body. Use this field to detect concurrent edits by other users.

Set expected_version to the version number you last loaded. If another user saved a newer version, the request returns 409 Conflict with the following fields:

Field Type Description
code string WORKFLOW_VERSION_CONFLICT
title string Human-readable error title.
detail string Description of the conflict.
current_version integer The latest version number on the server.
expected_version integer The version number you sent in the request.
created_by_username string Username of the user who saved the newer version.
created_at datetime Timestamp when the newer version was saved.
current_version_name string or null Display name of the conflicting version, if one was set.
retryable boolean Alwaysfalse. Re-fetch the latest version before retrying.

If you omit expected_version, the endpoint does not check for concurrent edits.

Workflow response fields related to versioning

The workflow response (GET /workflows/{workflow_id} and list endpoints) includes the following fields that relate to versioning and publishing state:

Field Type Description
current_version integer The latest version number for this workflow.
published_version_number integer or null The version number that is currently published. Null when no version is published.
has_validation_issues boolean true when the current draft has unresolved validation errors or warnings.
validation_result object or null Errors and warnings from the most recent save. Present only in create (POST) and update (PATCH) responses. SeeValidation result format.

List versions

GET /workflows/{workflow_id}/versions

Returns all versions for the specified workflow in descending order (newest first). Results are paginated using cursor-based pagination.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.

Query parameters:

Parameter Type Default Description
limit integer 20 Maximum number of results per page. Must be between 1 and 100.
cursor string None Pagination cursor from a previous response. Pass the cursor value from the response to retrieve the next page.
sort string None Sort parameter. Use a field name to sort ascending or prefix with- for descending, for example-created_at.
include_total boolean false Include the total count of versions in the response. Not required for standard pagination.

Response fields (per version):

Field Type Description
id UUID Unique version identifier.
workflow_id UUID Parent workflow identifier.
version integer Sequential version number, starting at 1.
status string Version state:draft,published, orpreviously_published.
name string User-provided display name for this version. Not set by default.
last_published_at datetime or null Timestamp when this version was last published. Null if the version has never been published.
last_unpublished_at datetime or null Timestamp when this version was last unpublished. Null if the version has never been unpublished.
change_description string Description of what changed in this version. Not set by default.
schema_version string Workflow definition schema version (for example,2.0.0).
workflow_definition object The complete workflow definition for this version.
created_by UUID Identifier of the user who created this version.
created_by_username string or null Username of the user who created this version.
created_at datetime Timestamp when this version was created.
updated_at datetime Timestamp when this version was last updated.

Get a specific version

GET /workflows/{workflow_id}/versions/{version}

Returns a single version by workflow identifier and version number.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.
version integer The version number to retrieve.

Returns 404 if the workflow or version does not exist.

Publish a version

POST /workflows/{workflow_id}/versions/{version}/publish

Publishes the specified version, making it the active version for all triggers and new runs. If another version is currently published, automation orchestrator demotes it to previously_published status.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.
version integer The version number to publish.

Request body (optional):

Field Type Constraints Description
name string Maximum 255 characters A display name for this published version.
change_description string Maximum 1024 characters A description of why this version is being published.
workflow_definition object Must pass validation A workflow definition to publish directly. When provided, creates a new version with this definition and publishes it, allowing you to publish unsaved changes without a separate save step. The definition is validated before publishing.
expected_version integer Optional The version number you last loaded. If a newer version exists, the request returns409 Conflict. SeeConcurrent edit detection.

Response fields (in addition to standard workflow fields):

Field Type Description
warning string A warning message from the publish operation. Empty when publishing completes without issues. Contains a message when part of the publish did not fully complete, for example when scheduled triggers could not be activated.

Behavior:

  • Validates the workflow definition before publishing. If the definition contains errors or warnings, the request returns 409 Conflict and the version is not published. The save endpoints always return 200 and include any validation findings in the response body without rejecting the save. The publish endpoint is stricter: it rejects definitions with errors or warnings. The endpoint also rejects a workflow with no steps.
  • Activates webhook triggers defined in the published version.
  • Creates or updates scheduled triggers to use the published version. If scheduled triggers cannot be activated, the publish still succeeds. The response includes a warning field with instructions to republish.
  • If the specified version is already published, updates only the name and change_description fields.

Unpublish a workflow

POST /workflows/{workflow_id}/unpublish

Removes the published status from the current published version and deactivates all triggers.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.

Behavior:

  • Automation orchestrator demotes the published version to previously_published status.
  • Webhook triggers stop accepting requests.
  • Automation orchestrator deactivates scheduled triggers.
  • Runs that are already in progress continue to completion.

Returns 400 if no version is currently published.

Restore a version

POST /workflows/{workflow_id}/versions/{version}/restore

Creates a new draft version by copying the definition from the specified version. The new version becomes the current version. Automation orchestrator does not activate or modify triggers.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.
version integer The version number to restore from.

Behavior:

  • Creates a new draft version with the next sequential version number.
  • Sets the change description to record the source version, using the version name, timestamp, or version number.
  • Does not activate triggers or change the published version.
  • If the selected version's definition is identical to the current version, returns the current version without creating a duplicate.

Export a version

GET /workflows/{workflow_id}/versions/{version}/export

Downloads the workflow definition for the specified version as a JSON file. The response includes a Content-Disposition header with a sanitized filename based on the workflow name and version number.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.
version integer The version number to export.

Returns a JSON file with content type application/json and a Content-Disposition: attachment header. The file contains the complete workflow definition for the specified version.

Returns 404 if the workflow or version does not exist.

Update version metadata

PATCH /workflows/{workflow_id}/versions/{version}

Updates the display name or change description for a specific version without republishing it.

Path parameters:

Parameter Type Description
workflow_id UUID The workflow identifier.
version integer The version number to update.

Request body:

Field Type Constraints Description
name string Maximum 255 characters A display name for this version. Sendnull to clear an existing name.
change_description string Maximum 1024 characters A description of what changed in this version. Sendnull to clear an existing description.

Both fields are optional. Automation orchestrator updates only the fields you include in the request body and leaves omitted fields unchanged.

Returns the updated version object. See List versions for the response field definitions.

Returns 404 if the workflow or version does not exist.

Validate a definition

POST /workflows/validate

Validates a workflow definition without saving it or creating a new version. Returns a result that lists each error and warning with its severity, category, and location.

Request body:

Field Type Description
workflow_definition object The workflow definition to validate.

Returns 200 with findings if the definition is valid or contains only warnings. Returns 422 with findings if the definition contains errors.

The response uses the same format described in Validation result format.

Validation result format

Validation results from the /validate endpoint and from create (POST) and update (PATCH) responses use the following format.

Top-level fields:

Field Type Description
is_valid boolean true when no errors exist.
error_count integer Number of errors found.
warning_count integer Number of warnings found.
findings array List of validation findings, errors first.

Finding fields:

Field Type Description
severity string error orwarning.
category string What kind of issue was found:schema_version,missing_field,schema_violation,invalid_reference,cycle_detected,orphaned_node, orconverge_configuration.
message string Human-readable description of the issue.
node_id string or null Node identifier for node-level findings. Null for workflow-level issues.
field_path string or null Path within the node configuration, for exampleconfig.url. Null when the finding applies to the node as a whole.

Version status values

Status Description
draft Saved but not published. Does not affect triggers or scheduled runs.
published The active version used by all new runs. Only one version per workflow can be published.
previously_published A version that was published previously but has been replaced or the workflow was unpublished.