Manage workflows through the API

The automation orchestrator REST API provides endpoints for the complete workflow lifecycle, including workflow definitions, versioning, execution, monitoring, and validation. The following tables list each endpoint, its HTTP method, and the required permission.

Workflow management

All paths are relative to the /api/v1 prefix.

Table 1. Workflow management endpoints
Method Endpoint Description Permission
POST /workflows Create a new workflow definition. Requiresproject_id andworkflow_definition in the request body. workflow:create
GET /workflows List all workflows visible to the authenticated user. workflow:read
GET /workflows/{workflow_id} Retrieve a single workflow with its current version. workflow:read
PATCH /workflows/{workflow_id} Update workflow metadata or definition. Creates a new version if the definition changes. Accepts an optionalexpected_version field for optimistic concurrency control; returns409 Conflict if a newer version exists. workflow:update
DELETE /workflows/{workflow_id}

Permanently deletes the workflow, all of its versions, and all execution history. Records are removed from the database and cannot be restored through automation orchestrator. Returns 204 No Content.

 workflow:delete
POST /workflows/{workflow_id}/test Test a single workflow node without executing the full workflow. Returns201 Created. workflow:create
Note:
Workflow, workflow-version, and execution API responses no longer include the deleted_at and deleted_by fields. You must update API clients that read or model these fields.

Workflow versioning

Table 2. Workflow versioning endpoints
Method Endpoint Description Permission
GET /workflows/{workflow_id}/versions List all versions of a workflow. workflow:read
GET /workflows/{workflow_id}/versions/{version} Retrieve a specific workflow version, where{version} is an integer version number. workflow:read
POST /workflows/{workflow_id}/versions/{version}/publish Publish a workflow version, making it available for execution. Accepts an optional request body withpublish_name,change_description,workflow_definition, andexpected_version fields. Returns409 Conflict ifexpected_version is lower than the current version. workflow:update
POST /workflows/{workflow_id}/unpublish Unpublish a workflow, preventing new executions. workflow:update
POST /workflows/{workflow_id}/versions/{version}/restore Restore a previous version as a new draft. workflow:update
GET /workflows/{workflow_id}/versions/{version}/export Export a version definition as a JSON file. workflow:read

Execution management

Execution endpoints use a top-level /executions path, not nested under workflows.

Table 3. Execution management endpoints
Method Endpoint Description Permission
POST /executions

Trigger a new workflow execution with optional input parameters

Requires workflow_id and trigger_node_id. Accepts optional input_data and use_published. Set use_published: true

Returns201 Created.

 execution:run
GET /executions List executions visible to the authenticated user. execution:read
GET /executions/{execution_id} Retrieve a single execution with its current status and outputs. execution:read
POST /executions/{execution_id}/cancel Cancel a running execution. Returns202 Accepted. execution:run
POST /executions/{execution_id}/retry Retry a completed or failed execution. Creates a new execution using the same workflow version, inputs, and trigger as the original. Returns201 Created. execution:run

Execution status values: pending, running, paused, completed, completed_with_errors, failed, cancelled.

Terminal states: completed, completed_with_errors, failed, cancelled.

Track a workflow execution to completion

Workflow execution is asynchronous. A POST /executions request returns 201 Created immediately with the execution ID. The workflow runs in the background.

Poll GET /executions/{execution_id} until the status field reaches a terminal state.

When polling:

  • Start with a short interval, such as 2 seconds, and increase it with exponential backoff for long-running workflows.
  • If the API returns 429 Too Many Requests, wait for the duration in the Retry-After header before the next request.

For real-time updates without polling, connect to the WebSocket endpoint at /ws/workflows/v1/executions/{execution_id}.

For a complete worked example including authentication, workflow creation, and execution polling, see Integrate external systems with the REST API.

Activity execution monitoring

Table 4. Activity execution monitoring endpoints
Method Endpoint Description Permission
GET /executions/{execution_id}/activities List activity executions for a workflow execution, showing individual node results. execution:read
POST /executions/{execution_id}/activities/{activity_id}/signal Send a signal to a waiting activity, such as providing approval or input. execution:run

Webhook triggers

Webhook trigger endpoints receive inbound payloads from external systems to start workflow executions. These endpoints require a service account Bearer token. Each webhook trigger is bound to one or more authorized service accounts. The API verifies that the calling service account is explicitly authorized for the specific trigger.

Table 5. Webhook trigger endpoints
Method Endpoint Description Permission
POST /webhooks/{path} Receive an external webhook payload and trigger a workflow execution. Service account Bearer token (per-trigger authorization)
POST /webhooks/eda/{path} Receive an Event-Driven Ansible webhook payload and trigger a workflow execution. Service account Bearer token (per-trigger authorization)

Workflow validation

Table 6. Workflow validation endpoints
Method Endpoint Description Permission
POST /workflows/validate Validate a workflow definition without saving it. workflow:create
POST /workflows/validate/detailed Perform detailed validation with node-level error reporting. workflow:create