OpenStack Workflow Service API

This is a reference for the OpenStack Workflow Service API which is provided by the Mistral project.

Workflows (workflows)

Manage workflow definitions.

A workflow is the main building block of Mistral. It represents a process that can be described in a various number of ways and that can do some job interesting to the end user. Each workflow consists of tasks (at least one) describing what exact steps should be made during workflow execution.

GET
/v2/workflows

List Workflows

Lists all workflows.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

name (Optional)

query

string

Filter by workflow name.

input (Optional)

query

string

Filter by workflow input.

definition (Optional)

query

string

Filter by workflow definition.

tags (Optional)

query

string

Filter by workflow tags.

scope (Optional)

query

string

Filter by workflow scope.

project_id (Optional)

query

string

Filter by project ID. Admin only.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

all_projects (Optional)

query

boolean

If set to true, return resources from all projects. Admin only.

namespace (Optional)

query

string

The namespace of the resource.

Response

Name

In

Type

Description

workflows

body

array

A list of workflow objects.

id

body

string

The UUID of the workflow.

name

body

string

The name of the workflow.

namespace (Optional)

body

string

The namespace of the workflow.

input (Optional)

body

string

The input parameter definitions for the workflow.

interface (Optional)

body

object

A dictionary containing the input and output interface of the workflow.

definition

body

string

The workflow definition written in Mistral v2 DSL.

checksum (Optional)

body

string

MD5 checksum of the workflow definition.

tags (Optional)

body

array

A list of tags associated with the workflow.

scope (Optional)

body

string

The scope of the workflow. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workflow.

created_at

body

string

The date and time when the workflow was created.

updated_at (Optional)

body

string

The date and time when the workflow was last updated.
POST
/v2/workflows

Create Workflow

Creates one or more workflows from a YAML definition.

The request body should contain a YAML workflow definition conforming to the Mistral v2 DSL. Multiple workflows can be defined in a single YAML definition.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name

In

Type

Description

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

skip_validation (Optional)

query

boolean

If set to true, skip definition validation on create or update.

The request body is a YAML workflow definition in text/plain format.

Response

Name

In

Type

Description

workflows

body

array

A list of workflow objects.

id

body

string

The UUID of the workflow.

name

body

string

The name of the workflow.

namespace (Optional)

body

string

The namespace of the workflow.

input (Optional)

body

string

The input parameter definitions for the workflow.

interface (Optional)

body

object

A dictionary containing the input and output interface of the workflow.

definition

body

string

The workflow definition written in Mistral v2 DSL.

checksum (Optional)

body

string

MD5 checksum of the workflow definition.

tags (Optional)

body

array

A list of tags associated with the workflow.

scope (Optional)

body

string

The scope of the workflow. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workflow.

created_at

body

string

The date and time when the workflow was created.

updated_at (Optional)

body

string

The date and time when the workflow was last updated.
GET
/v2/workflows/{workflow_identifier}

Show Workflow

Shows details for a workflow.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workflow_identifier

path

string

The name or UUID of the workflow.

namespace (Optional)

query

string

The namespace of the resource.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

Response

Name

In

Type

Description

id

body

string

The UUID of the workflow.

name

body

string

The name of the workflow.

namespace (Optional)

body

string

The namespace of the workflow.

input (Optional)

body

string

The input parameter definitions for the workflow.

interface (Optional)

body

object

A dictionary containing the input and output interface of the workflow.

definition

body

string

The workflow definition written in Mistral v2 DSL.

checksum (Optional)

body

string

MD5 checksum of the workflow definition.

tags (Optional)

body

array

A list of tags associated with the workflow.

scope (Optional)

body

string

The scope of the workflow. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workflow.

created_at

body

string

The date and time when the workflow was created.

updated_at (Optional)

body

string

The date and time when the workflow was last updated.
PUT
/v2/workflows/{workflow_identifier}

Update Workflow

Updates one or more workflows.

The request body should contain a YAML workflow definition conforming to the Mistral v2 DSL. If a workflow identifier is provided in the URL, only a single workflow can be updated at a time, and it must be identified by UUID.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workflow_identifier

path

string

The name or UUID of the workflow.

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

skip_validation (Optional)

query

boolean

If set to true, skip definition validation on create or update.

The request body is a YAML workflow definition in text/plain format.

Response

Name

In

Type

Description

workflows

body

array

A list of workflow objects.

id

body

string

The UUID of the workflow.

name

body

string

The name of the workflow.

namespace (Optional)

body

string

The namespace of the workflow.

input (Optional)

body

string

The input parameter definitions for the workflow.

interface (Optional)

body

object

A dictionary containing the input and output interface of the workflow.

definition

body

string

The workflow definition written in Mistral v2 DSL.

checksum (Optional)

body

string

MD5 checksum of the workflow definition.

tags (Optional)

body

array

A list of tags associated with the workflow.

scope (Optional)

body

string

The scope of the workflow. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workflow.

created_at

body

string

The date and time when the workflow was created.

updated_at (Optional)

body

string

The date and time when the workflow was last updated.
DELETE
/v2/workflows/{workflow_identifier}

Delete Workflow

Deletes a workflow.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workflow_identifier

path

string

The name or UUID of the workflow.

namespace (Optional)

query

string

The namespace of the resource.

Response

There is no body content for the response of a successful DELETE action.

Workbooks (workbooks)

Manage workbook definitions.

A workbook is a container for workflows, actions, and triggers that are logically related. It provides a convenient way to package related definitions together using a single YAML definition file.

GET
/v2/workbooks

List Workbooks

Lists all workbooks.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

name (Optional)

query

string

Filter by workbook name.

definition (Optional)

query

string

Filter by workbook definition.

tags (Optional)

query

string

Filter by workbook tags.

scope (Optional)

query

string

Filter by workbook scope.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

namespace (Optional)

query

string

The namespace of the resource.

Response

Name

In

Type

Description

workbooks

body

array

A list of workbook objects.

id

body

string

The UUID of the workbook.

name

body

string

The name of the workbook.

namespace (Optional)

body

string

The namespace of the workbook.

definition

body

string

The workbook definition written in Mistral v2 DSL.

tags (Optional)

body

array

A list of tags associated with the workbook.

scope (Optional)

body

string

The scope of the workbook. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workbook.

created_at

body

string

The date and time when the workbook was created.

updated_at (Optional)

body

string

The date and time when the workbook was last updated.
POST
/v2/workbooks

Create Workbook

Creates a workbook from a YAML definition.

The request body should contain a YAML workbook definition conforming to the Mistral v2 DSL.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name

In

Type

Description

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

skip_validation (Optional)

query

boolean

If set to true, skip definition validation on create or update.

The request body is a YAML workbook definition in text/plain format.

Response

Name

In

Type

Description

id

body

string

The UUID of the workbook.

name

body

string

The name of the workbook.

namespace (Optional)

body

string

The namespace of the workbook.

definition

body

string

The workbook definition written in Mistral v2 DSL.

tags (Optional)

body

array

A list of tags associated with the workbook.

scope (Optional)

body

string

The scope of the workbook. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workbook.

created_at

body

string

The date and time when the workbook was created.

updated_at (Optional)

body

string

The date and time when the workbook was last updated.
GET
/v2/workbooks/{workbook_name}

Show Workbook

Shows details for a workbook.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workbook_name

path

string

The name of the workbook.

namespace (Optional)

query

string

The namespace of the resource.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

Response

Name

In

Type

Description

id

body

string

The UUID of the workbook.

name

body

string

The name of the workbook.

namespace (Optional)

body

string

The namespace of the workbook.

definition

body

string

The workbook definition written in Mistral v2 DSL.

tags (Optional)

body

array

A list of tags associated with the workbook.

scope (Optional)

body

string

The scope of the workbook. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workbook.

created_at

body

string

The date and time when the workbook was created.

updated_at (Optional)

body

string

The date and time when the workbook was last updated.
PUT
/v2/workbooks

Update Workbook

Updates a workbook.

The request body should contain a YAML workbook definition conforming to the Mistral v2 DSL. The workbook is identified by name within the definition.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

skip_validation (Optional)

query

boolean

If set to true, skip definition validation on create or update.

The request body is a YAML workbook definition in text/plain format.

Response

Name

In

Type

Description

id

body

string

The UUID of the workbook.

name

body

string

The name of the workbook.

namespace (Optional)

body

string

The namespace of the workbook.

definition

body

string

The workbook definition written in Mistral v2 DSL.

tags (Optional)

body

array

A list of tags associated with the workbook.

scope (Optional)

body

string

The scope of the workbook. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the workbook.

created_at

body

string

The date and time when the workbook was created.

updated_at (Optional)

body

string

The date and time when the workbook was last updated.
DELETE
/v2/workbooks/{workbook_name}

Delete Workbook

Deletes a workbook.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workbook_name

path

string

The name of the workbook.

namespace (Optional)

query

string

The namespace of the resource.

Response

There is no body content for the response of a successful DELETE action.

Tasks (tasks)

Manage task executions.

A task represents a particular step of a workflow execution. It is created by the Mistral engine when a workflow is running and tracks the state and result of an individual unit of work within the workflow.

GET
/v2/tasks

List Tasks

Lists all task executions.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

name (Optional)

query

string

Filter by task name.

workflow_name (Optional)

query

string

Filter by the name of the workflow associated with the task.

workflow_id (Optional)

query

string

Filter by the ID of the workflow associated with the task.

workflow_execution_id (Optional)

query

string

Filter by the workflow execution ID.

tags (Optional)

query

string

Filter by task tags.

state (Optional)

query

string

Filter by task state. Valid values are IDLE, RUNNING, SUCCESS, ERROR, and DELAYED.

state_info (Optional)

query

string

Filter by task state info.

result (Optional)

query

string

Filter by task result.

published (Optional)

query

string

Filter by task published variables.

processed (Optional)

query

boolean

Filter by whether the task has been processed.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

reset (Optional)

query

boolean

Filter by reset flag.

env (Optional)

query

string

Filter by task environment.

Response

Name

In

Type

Description

tasks

body

array

A list of task objects.

id

body

string

The UUID of the task execution.

name

body

string

The name of the task.

type

body

string

The type of the task (e.g., ACTION, WORKFLOW).

workflow_name

body

string

The name of the workflow that the task belongs to.

workflow_namespace (Optional)

body

string

The namespace of the workflow that the task belongs to.

workflow_id

body

string

The UUID of the workflow that the task belongs to.

workflow_execution_id

body

string

The UUID of the workflow execution that the task belongs to.

tags (Optional)

body

array

A list of tags associated with the task.

state

body

string

The current state of the task. One of IDLE, RUNNING, SUCCESS, ERROR, or DELAYED.

state_info (Optional)

body

string

An optional state information string providing additional details.

project_id (Optional)

body

string

The UUID of the project that owns the task.

runtime_context (Optional)

body

object

A JSON object containing runtime context information.

result (Optional)

body

string

The result of the task execution.

published (Optional)

body

object

A JSON object containing published task variables.

published_global (Optional)

body

object

A JSON object containing globally published task variables.

processed (Optional)

body

boolean

Whether the task has been processed by the engine.

created_at

body

string

The date and time when the task was created.

updated_at (Optional)

body

string

The date and time when the task was last updated.

started_at (Optional)

body

string

The date and time when the task started executing.

finished_at (Optional)

body

string

The date and time when the task finished executing.
GET
/v2/tasks/{task_id}

Show Task

Shows details for a task execution.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

task_id

path

string

The UUID of the task execution.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

Response

Name

In

Type

Description

id

body

string

The UUID of the task execution.

name

body

string

The name of the task.

type

body

string

The type of the task (e.g., ACTION, WORKFLOW).

workflow_name

body

string

The name of the workflow that the task belongs to.

workflow_namespace (Optional)

body

string

The namespace of the workflow that the task belongs to.

workflow_id

body

string

The UUID of the workflow that the task belongs to.

workflow_execution_id

body

string

The UUID of the workflow execution that the task belongs to.

tags (Optional)

body

array

A list of tags associated with the task.

state

body

string

The current state of the task. One of IDLE, RUNNING, SUCCESS, ERROR, or DELAYED.

state_info (Optional)

body

string

An optional state information string providing additional details.

project_id (Optional)

body

string

The UUID of the project that owns the task.

runtime_context (Optional)

body

object

A JSON object containing runtime context information.

result (Optional)

body

string

The result of the task execution.

published (Optional)

body

object

A JSON object containing published task variables.

published_global (Optional)

body

object

A JSON object containing globally published task variables.

processed (Optional)

body

boolean

Whether the task has been processed by the engine.

created_at

body

string

The date and time when the task was created.

updated_at (Optional)

body

string

The date and time when the task was last updated.

started_at (Optional)

body

string

The date and time when the task started executing.

finished_at (Optional)

body

string

The date and time when the task finished executing.
PUT
/v2/tasks/{task_id}

Rerun Task

Reruns or skips a task execution.

This operation can be used to rerun a failed task or to skip a task that is in ERROR state. To rerun a task, set state to RUNNING and reset to true. To skip a task, set state to SKIPPED.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

task_id

path

string

The UUID of the task execution.

state (Optional)

body

string

The new state for the task. Valid values are RUNNING (to rerun) and SKIPPED (to skip).

reset (Optional)

body

boolean

If true, reset the task state before rerunning. Required when rerunning a task that is in ERROR state.

env (Optional)

body

object

A JSON object containing environment variables for the task.

Response

Name

In

Type

Description

id

body

string

The UUID of the task execution.

name

body

string

The name of the task.

type

body

string

The type of the task (e.g., ACTION, WORKFLOW).

workflow_name

body

string

The name of the workflow that the task belongs to.

workflow_namespace (Optional)

body

string

The namespace of the workflow that the task belongs to.

workflow_id

body

string

The UUID of the workflow that the task belongs to.

workflow_execution_id

body

string

The UUID of the workflow execution that the task belongs to.

tags (Optional)

body

array

A list of tags associated with the task.

state

body

string

The current state of the task. One of IDLE, RUNNING, SUCCESS, ERROR, or DELAYED.

state_info (Optional)

body

string

An optional state information string providing additional details.

project_id (Optional)

body

string

The UUID of the project that owns the task.

runtime_context (Optional)

body

object

A JSON object containing runtime context information.

result (Optional)

body

string

The result of the task execution.

published (Optional)

body

object

A JSON object containing published task variables.

published_global (Optional)

body

object

A JSON object containing globally published task variables.

processed (Optional)

body

boolean

Whether the task has been processed by the engine.

created_at

body

string

The date and time when the task was created.

updated_at (Optional)

body

string

The date and time when the task was last updated.

started_at (Optional)

body

string

The date and time when the task started executing.

finished_at (Optional)

body

string

The date and time when the task finished executing.

Executions (executions)

Manage workflow executions.

An execution represents one run of a workflow. When a workflow is executed, Mistral creates an execution object that tracks the state, input, output, and other runtime information about the running workflow.

GET
/v2/executions

List Executions

Lists all workflow executions.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

workflow_name (Optional)

query

string

Filter by the name of the workflow associated with the execution.

workflow_id (Optional)

query

string

Filter by the ID of the workflow associated with the execution.

description (Optional)

query

string

Filter by execution description.

tags (Optional)

query

string

Filter by execution tags.

params (Optional)

query

string

Filter by execution params.

task_execution_id (Optional)

query

string

Filter by parent task execution ID.

root_execution_id (Optional)

query

string

Filter by root execution ID.

state (Optional)

query

string

Filter by execution state. Valid values are IDLE, RUNNING, SUCCESS, ERROR, PAUSED, and CANCELLED.

state_info (Optional)

query

string

Filter by execution state info.

input (Optional)

query

string

Filter by execution input.

output (Optional)

query

string

Filter by execution output.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

include_output (Optional)

query

boolean

If set to true, include the output field in the list response. By default, the output field is not included in list results.

project_id (Optional)

query

string

Filter by project ID. Admin only.

all_projects (Optional)

query

boolean

If set to true, return resources from all projects. Admin only.

nulls (Optional)

query

string

Comma-separated list of field names that should be filtered as NULL.

Response

Name

In

Type

Description

executions

body

array

A list of execution objects.

id

body

string

The UUID of the execution. Immutable and auto-assigned, or can be specified by the API client if using source_execution_id.

workflow_id (Optional)

body

string

The UUID of the workflow associated with the execution.

workflow_name (Optional)

body

string

The name of the workflow associated with the execution.

workflow_namespace (Optional)

body

string

The namespace of the workflow associated with the execution.

description (Optional)

body

string

A description of the workflow execution.

tags (Optional)

body

array

A list of tags associated with the execution.

params (Optional)

body

object

A JSON object defining workflow type specific parameters. Supported keys include:

  • task_name - the name of the target task (reverse workflows only).

  • env - a string or JSON object containing environment variables.

  • evaluate_env - controls recursive evaluation of env.

  • notify - a list of publishers to notify on state changes.

task_execution_id (Optional)

body

string

Reference to the parent task execution UUID.

root_execution_id (Optional)

body

string

Reference to the root execution UUID.

state

body

string

The current state of the execution. One of IDLE, RUNNING, SUCCESS, ERROR, PAUSED, or CANCELLED.

state_info (Optional)

body

string

An optional state information string providing additional details about the current state.

input (Optional)

body

object

A JSON object containing the workflow input values.

output (Optional)

body

object

A JSON object containing the workflow output values.

created_at

body

string

The date and time when the execution was created.

updated_at (Optional)

body

string

The date and time when the execution was last updated.

project_id (Optional)

body

string

The UUID of the project that owns the execution.
POST
/v2/executions

Create Execution

Creates and starts a new workflow execution.

Either workflow_id or workflow_name must be provided to identify the workflow to execute. Alternatively, source_execution_id can be used to replicate an existing execution.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

workflow_id (Optional)

body

string

The UUID of the workflow to execute. Either workflow_id or workflow_name must be provided.

workflow_name (Optional)

body

string

The name of the workflow to execute. Either workflow_id or workflow_name must be provided.

workflow_namespace (Optional)

body

string

The namespace of the workflow associated with the execution.

description (Optional)

body

string

A description of the workflow execution.

input (Optional)

body

object

A JSON object containing the workflow input values.

params (Optional)

body

object

A JSON object defining workflow type specific parameters. Supported keys include:

  • task_name - the name of the target task (reverse workflows only).

  • env - a string or JSON object containing environment variables.

  • evaluate_env - controls recursive evaluation of env.

  • notify - a list of publishers to notify on state changes.

source_execution_id (Optional)

body

string

Reference to a source workflow execution UUID. When specified, the API replicates the source execution, copying the workflow, input, params, and description.

Response

Name

In

Type

Description

id

body

string

The UUID of the execution. Immutable and auto-assigned, or can be specified by the API client if using source_execution_id.

workflow_id (Optional)

body

string

The UUID of the workflow associated with the execution.

workflow_name (Optional)

body

string

The name of the workflow associated with the execution.

workflow_namespace (Optional)

body

string

The namespace of the workflow associated with the execution.

description (Optional)

body

string

A description of the workflow execution.

tags (Optional)

body

array

A list of tags associated with the execution.

params (Optional)

body

object

A JSON object defining workflow type specific parameters. Supported keys include:

  • task_name - the name of the target task (reverse workflows only).

  • env - a string or JSON object containing environment variables.

  • evaluate_env - controls recursive evaluation of env.

  • notify - a list of publishers to notify on state changes.

task_execution_id (Optional)

body

string

Reference to the parent task execution UUID.

root_execution_id (Optional)

body

string

Reference to the root execution UUID.

state

body

string

The current state of the execution. One of IDLE, RUNNING, SUCCESS, ERROR, PAUSED, or CANCELLED.

state_info (Optional)

body

string

An optional state information string providing additional details about the current state.

input (Optional)

body

object

A JSON object containing the workflow input values.

output (Optional)

body

object

A JSON object containing the workflow output values.

created_at

body

string

The date and time when the execution was created.

updated_at (Optional)

body

string

The date and time when the execution was last updated.

project_id (Optional)

body

string

The UUID of the project that owns the execution.
GET
/v2/executions/{execution_id}

Show Execution

Shows details for an execution.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

execution_id

path

string

The UUID of the execution.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

Response

Name

In

Type

Description

id

body

string

The UUID of the execution. Immutable and auto-assigned, or can be specified by the API client if using source_execution_id.

workflow_id (Optional)

body

string

The UUID of the workflow associated with the execution.

workflow_name (Optional)

body

string

The name of the workflow associated with the execution.

workflow_namespace (Optional)

body

string

The namespace of the workflow associated with the execution.

description (Optional)

body

string

A description of the workflow execution.

tags (Optional)

body

array

A list of tags associated with the execution.

params (Optional)

body

object

A JSON object defining workflow type specific parameters. Supported keys include:

  • task_name - the name of the target task (reverse workflows only).

  • env - a string or JSON object containing environment variables.

  • evaluate_env - controls recursive evaluation of env.

  • notify - a list of publishers to notify on state changes.

task_execution_id (Optional)

body

string

Reference to the parent task execution UUID.

root_execution_id (Optional)

body

string

Reference to the root execution UUID.

source_execution_id (Optional)

body

string

Reference to a source workflow execution UUID. When specified, the API replicates the source execution, copying the workflow, input, params, and description.

state

body

string

The current state of the execution. One of IDLE, RUNNING, SUCCESS, ERROR, PAUSED, or CANCELLED.

state_info (Optional)

body

string

An optional state information string providing additional details about the current state.

input (Optional)

body

object

A JSON object containing the workflow input values.

output (Optional)

body

object

A JSON object containing the workflow output values.

created_at

body

string

The date and time when the execution was created.

updated_at (Optional)

body

string

The date and time when the execution was last updated.

project_id (Optional)

body

string

The UUID of the project that owns the execution.

published_global (Optional)

body

object

A JSON object containing globally published variables.
PUT
/v2/executions/{execution_id}

Update Execution

Updates an execution.

This can be used to pause, resume, or cancel an execution, update its description, or modify its environment variables.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

execution_id

path

string

The UUID of the execution.

state (Optional)

body

string

The new state for the execution. Valid transitions: RUNNING to PAUSED, PAUSED to RUNNING, or any running state to CANCELLED, SUCCESS, or ERROR.

description (Optional)

body

string

An updated description for the execution.

params (Optional)

body

object

A JSON object with updated parameters. Currently only env can be updated this way.

Response

Name

In

Type

Description

id

body

string

The UUID of the execution. Immutable and auto-assigned, or can be specified by the API client if using source_execution_id.

workflow_id (Optional)

body

string

The UUID of the workflow associated with the execution.

workflow_name (Optional)

body

string

The name of the workflow associated with the execution.

workflow_namespace (Optional)

body

string

The namespace of the workflow associated with the execution.

description (Optional)

body

string

A description of the workflow execution.

tags (Optional)

body

array

A list of tags associated with the execution.

params (Optional)

body

object

A JSON object defining workflow type specific parameters. Supported keys include:

  • task_name - the name of the target task (reverse workflows only).

  • env - a string or JSON object containing environment variables.

  • evaluate_env - controls recursive evaluation of env.

  • notify - a list of publishers to notify on state changes.

task_execution_id (Optional)

body

string

Reference to the parent task execution UUID.

root_execution_id (Optional)

body

string

Reference to the root execution UUID.

state

body

string

The current state of the execution. One of IDLE, RUNNING, SUCCESS, ERROR, PAUSED, or CANCELLED.

state_info (Optional)

body

string

An optional state information string providing additional details about the current state.

input (Optional)

body

object

A JSON object containing the workflow input values.

output (Optional)

body

object

A JSON object containing the workflow output values.

created_at

body

string

The date and time when the execution was created.

updated_at (Optional)

body

string

The date and time when the execution was last updated.

project_id (Optional)

body

string

The UUID of the project that owns the execution.
DELETE
/v2/executions/{execution_id}

Delete Execution

Deletes an execution.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

execution_id

path

string

The UUID of the execution.

force (Optional)

query

boolean

If set to true, force delete the execution even if it is running.

Response

There is no body content for the response of a successful DELETE action.

Actions (actions)

Manage action definitions.

An action defines a particular step that can be performed as part of a workflow task. Mistral comes with a set of built-in system actions (e.g., HTTP requests, email sending) and also allows users to define custom actions using the Mistral v2 DSL.

Note

Action name and description are immutable. They are inferred from the action definition when the action is created.

GET
/v2/actions

List Actions

Lists all actions.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

name (Optional)

query

string

Filter by action name.

scope (Optional)

query

string

Filter by action scope.

tags (Optional)

query

string

Filter by action tags.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

description (Optional)

query

string

Filter by action description.

definition (Optional)

query

string

Filter by action definition.

is_system (Optional)

query

boolean

Filter by whether the action is a system action.

input (Optional)

query

string

Filter by action input.

namespace (Optional)

query

string

The namespace of the resource.

Response

Name

In

Type

Description

actions

body

array

A list of action objects.

id

body

string

The UUID of the action.

name

body

string

The name of the action. Immutable; inferred from the action definition on creation.

is_system (Optional)

body

boolean

Whether the action is a built-in system action.

input (Optional)

body

string

The input parameter definitions for the action.

description (Optional)

body

string

A description of the action. Inferred from the action definition on creation.

tags (Optional)

body

array

A list of tags associated with the action.

definition

body

string

The action definition written in Mistral v2 DSL.

scope (Optional)

body

string

The scope of the action. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the action.

created_at

body

string

The date and time when the action was created.

updated_at (Optional)

body

string

The date and time when the action was last updated.

namespace (Optional)

body

string

The namespace of the action.
POST
/v2/actions

Create Action

Creates one or more actions from a YAML definition.

The request body should contain a YAML action definition conforming to the Mistral v2 DSL. Multiple actions can be defined in a single YAML definition.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name

In

Type

Description

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

The request body is a YAML action definition in text/plain format.

Response

Name

In

Type

Description

actions

body

array

A list of action objects.

id

body

string

The UUID of the action.

name

body

string

The name of the action. Immutable; inferred from the action definition on creation.

is_system (Optional)

body

boolean

Whether the action is a built-in system action.

input (Optional)

body

string

The input parameter definitions for the action.

description (Optional)

body

string

A description of the action. Inferred from the action definition on creation.

tags (Optional)

body

array

A list of tags associated with the action.

definition

body

string

The action definition written in Mistral v2 DSL.

scope (Optional)

body

string

The scope of the action. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the action.

created_at

body

string

The date and time when the action was created.

updated_at (Optional)

body

string

The date and time when the action was last updated.

namespace (Optional)

body

string

The namespace of the action.
GET
/v2/actions/{action_identifier}

Show Action

Shows details for an action.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

action_identifier

path

string

The name or UUID of the action.

namespace (Optional)

query

string

The namespace of the resource.

Response

Name

In

Type

Description

id

body

string

The UUID of the action.

name

body

string

The name of the action. Immutable; inferred from the action definition on creation.

is_system (Optional)

body

boolean

Whether the action is a built-in system action.

input (Optional)

body

string

The input parameter definitions for the action.

description (Optional)

body

string

A description of the action. Inferred from the action definition on creation.

tags (Optional)

body

array

A list of tags associated with the action.

definition

body

string

The action definition written in Mistral v2 DSL.

scope (Optional)

body

string

The scope of the action. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the action.

created_at

body

string

The date and time when the action was created.

updated_at (Optional)

body

string

The date and time when the action was last updated.

namespace (Optional)

body

string

The namespace of the action.
PUT
/v2/actions/{action_identifier}

Update Action

Updates one or more actions.

The request body should contain a YAML action definition conforming to the Mistral v2 DSL.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

action_identifier

path

string

The name or UUID of the action.

namespace (Optional)

query

string

The namespace of the resource.

scope (Optional)

query

string

The scope of the resource. Valid values are private and public.

The request body is a YAML action definition in text/plain format.

Response

Name

In

Type

Description

actions

body

array

A list of action objects.

id

body

string

The UUID of the action.

name

body

string

The name of the action. Immutable; inferred from the action definition on creation.

is_system (Optional)

body

boolean

Whether the action is a built-in system action.

input (Optional)

body

string

The input parameter definitions for the action.

description (Optional)

body

string

A description of the action. Inferred from the action definition on creation.

tags (Optional)

body

array

A list of tags associated with the action.

definition

body

string

The action definition written in Mistral v2 DSL.

scope (Optional)

body

string

The scope of the action. private or public.

project_id (Optional)

body

string

The UUID of the project that owns the action.

created_at

body

string

The date and time when the action was created.

updated_at (Optional)

body

string

The date and time when the action was last updated.

namespace (Optional)

body

string

The namespace of the action.
DELETE
/v2/actions/{action_identifier}

Delete Action

Deletes an action.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

action_identifier

path

string

The name or UUID of the action.

namespace (Optional)

query

string

The namespace of the resource.

Response

There is no body content for the response of a successful DELETE action.

Cron Triggers (cron_triggers)

Manage cron triggers.

A cron trigger is a scheduling mechanism that automatically starts a workflow execution based on a cron expression pattern. Cron triggers can be configured with a maximum number of remaining executions, after which the trigger is automatically removed.

GET
/v2/cron_triggers

List Cron Triggers

Lists all cron triggers.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

marker (Optional)

query

string

A resource UUID to use as a pagination marker. The list will contain resources that come after the marker.

limit (Optional)

query

integer

Maximum number of resources to return in a single result.

sort_keys (Optional)

query

string

Comma-separated list of sort keys. Each key specifies a column to sort by.

sort_dirs (Optional)

query

string

Comma-separated list of sort directions. Each direction corresponds to a key in sort_keys. Valid values are asc and desc.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

name (Optional)

query

string

Filter by cron trigger name.

workflow_name (Optional)

query

string

Filter by the name of the workflow associated with the trigger.

workflow_id (Optional)

query

string

Filter by the ID of the workflow associated with the trigger.

workflow_input (Optional)

query

string

Filter by the workflow input.

workflow_params (Optional)

query

string

Filter by the workflow parameters.

scope (Optional)

query

string

Filter by trigger scope.

pattern (Optional)

query

string

Filter by cron pattern.

remaining_executions (Optional)

query

integer

Filter by remaining number of executions.

first_execution_time (Optional)

query

string

Filter by first execution time.

next_execution_time (Optional)

query

string

Filter by next scheduled execution time.

created_at (Optional)

query

string

Filter by creation date.

updated_at (Optional)

query

string

Filter by last update date.

project_id (Optional)

query

string

Filter by project ID. Admin only.

all_projects (Optional)

query

boolean

If set to true, return resources from all projects. Admin only.

Response

Name

In

Type

Description

cron_triggers

body

array

A list of cron trigger objects.

id

body

string

The UUID of the cron trigger.

name

body

string

The name of the cron trigger.

workflow_name (Optional)

body

string

The name of the workflow to execute on trigger.

workflow_id (Optional)

body

string

The UUID of the workflow to execute on trigger.

workflow_input (Optional)

body

object

A JSON object containing input values for the triggered workflow executions.

workflow_params (Optional)

body

object

A JSON object containing parameters for the triggered workflow executions.

project_id (Optional)

body

string

The UUID of the project that owns the cron trigger.

scope (Optional)

body

string

The scope of the cron trigger. private or public.

pattern (Optional)

body

string

The cron expression pattern (e.g., */5 * * * * to run every 5 minutes). Uses standard cron syntax.

remaining_executions (Optional)

body

integer

The number of remaining executions for the trigger. Must be at least 1. Once this reaches 0, the trigger is automatically removed.

first_execution_time (Optional)

body

string

The date and time of the first execution. If not specified, the first execution is determined by the cron pattern.

next_execution_time (Optional)

body

string

The date and time of the next scheduled execution.

created_at

body

string

The date and time when the cron trigger was created.

updated_at (Optional)

body

string

The date and time when the cron trigger was last updated.
POST
/v2/cron_triggers

Create Cron Trigger

Creates a cron trigger.

Either workflow_name or workflow_id must be provided to identify the workflow to trigger. At least one of pattern or first_execution_time must be specified.

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name

In

Type

Description

name

body

string

The name for the new cron trigger.

workflow_name (Optional)

body

string

The name of the workflow to trigger. Either workflow_name or workflow_id must be provided.

workflow_id (Optional)

body

string

The UUID of the workflow to trigger. Either workflow_name or workflow_id must be provided.

workflow_input (Optional)

body

object

A JSON object containing input values for the triggered workflow executions.

workflow_params (Optional)

body

object

A JSON object containing parameters for the triggered workflow executions.

pattern (Optional)

body

string

The cron expression pattern (e.g., */5 * * * * to run every 5 minutes). Uses standard cron syntax.

first_execution_time (Optional)

body

string

The date and time of the first execution. If not specified, the first execution is determined by the cron pattern.

remaining_executions (Optional)

body

integer

The number of remaining executions for the trigger. Must be at least 1. Once this reaches 0, the trigger is automatically removed.

Response

Name

In

Type

Description

id

body

string

The UUID of the cron trigger.

name

body

string

The name of the cron trigger.

workflow_name (Optional)

body

string

The name of the workflow to execute on trigger.

workflow_id (Optional)

body

string

The UUID of the workflow to execute on trigger.

workflow_input (Optional)

body

object

A JSON object containing input values for the triggered workflow executions.

workflow_params (Optional)

body

object

A JSON object containing parameters for the triggered workflow executions.

project_id (Optional)

body

string

The UUID of the project that owns the cron trigger.

scope (Optional)

body

string

The scope of the cron trigger. private or public.

pattern (Optional)

body

string

The cron expression pattern (e.g., */5 * * * * to run every 5 minutes). Uses standard cron syntax.

remaining_executions (Optional)

body

integer

The number of remaining executions for the trigger. Must be at least 1. Once this reaches 0, the trigger is automatically removed.

first_execution_time (Optional)

body

string

The date and time of the first execution. If not specified, the first execution is determined by the cron pattern.

next_execution_time (Optional)

body

string

The date and time of the next scheduled execution.

created_at

body

string

The date and time when the cron trigger was created.

updated_at (Optional)

body

string

The date and time when the cron trigger was last updated.
GET
/v2/cron_triggers/{cron_trigger_identifier}

Show Cron Trigger

Shows details for a cron trigger.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

cron_trigger_identifier

path

string

The name or UUID of the cron trigger.

fields (Optional)

query

string

Comma-separated list of fields to include in the response. If not specified, all fields are returned.

Response

Name

In

Type

Description

id

body

string

The UUID of the cron trigger.

name

body

string

The name of the cron trigger.

workflow_name (Optional)

body

string

The name of the workflow to execute on trigger.

workflow_id (Optional)

body

string

The UUID of the workflow to execute on trigger.

workflow_input (Optional)

body

object

A JSON object containing input values for the triggered workflow executions.

workflow_params (Optional)

body

object

A JSON object containing parameters for the triggered workflow executions.

project_id (Optional)

body

string

The UUID of the project that owns the cron trigger.

scope (Optional)

body

string

The scope of the cron trigger. private or public.

pattern (Optional)

body

string

The cron expression pattern (e.g., */5 * * * * to run every 5 minutes). Uses standard cron syntax.

remaining_executions (Optional)

body

integer

The number of remaining executions for the trigger. Must be at least 1. Once this reaches 0, the trigger is automatically removed.

first_execution_time (Optional)

body

string

The date and time of the first execution. If not specified, the first execution is determined by the cron pattern.

next_execution_time (Optional)

body

string

The date and time of the next scheduled execution.

created_at

body

string

The date and time when the cron trigger was created.

updated_at (Optional)

body

string

The date and time when the cron trigger was last updated.
DELETE
/v2/cron_triggers/{cron_trigger_identifier}

Delete Cron Trigger

Deletes a cron trigger.

Normal response codes: 204

Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)

Request

Name

In

Type

Description

cron_trigger_identifier

path

string

The name or UUID of the cron trigger.

Response

There is no body content for the response of a successful DELETE action.