Chaos Mesh Workflows API
Create and manage chaos engineering workflows with multiple steps
OpenAPI Specification
openapi: 3.1.0
info:
title: Chaos Mesh Dashboard Archives Workflows API
description: The Chaos Mesh Dashboard API provides REST endpoints for managing chaos experiments, schedules, workflows, and events on Kubernetes clusters. Chaos Mesh is a cloud-native chaos engineering platform that supports fault injection into pods, nodes, networks, IO subsystems, and cloud provider resources. The Dashboard API is served by the chaos-dashboard component and is the backend for the Chaos Mesh web UI, accessible at /api on the dashboard server.
version: '2.5'
contact:
name: Chaos Mesh Community
url: https://chaos-mesh.org/community/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:2333/api
description: Default Chaos Mesh Dashboard server
tags:
- name: Workflows
description: Create and manage chaos engineering workflows with multiple steps
paths:
/workflows:
get:
operationId: listWorkflows
summary: Chaos Mesh List workflows
description: Returns a list of chaos engineering workflows from the Kubernetes cluster. Workflows allow orchestrating multiple chaos experiments as a sequence of steps with parallel execution, conditional branching, and timing controls. Results can be filtered by namespace, name, and status.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/namespaceParam'
- name: name
in: query
description: Filter workflows by name.
required: false
schema:
type: string
- name: status
in: query
description: Filter workflows by status.
required: false
schema:
type: string
responses:
'200':
description: List of workflows returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkflowMeta'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createWorkflow
summary: Chaos Mesh Create a new workflow
description: Creates a new chaos engineering workflow in the Kubernetes cluster. The request body is a Chaos Mesh Workflow custom resource that defines the entry point and sequence of chaos steps to execute, including serial and parallel task groups, suspends, and HTTP tasks.
tags:
- Workflows
requestBody:
description: Workflow custom resource definition.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KubeObjectDesc'
responses:
'200':
description: Workflow created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/workflows/{uid}:
get:
operationId: getWorkflow
summary: Chaos Mesh Get workflow details
description: Returns detailed information about a specific chaos workflow identified by its UID. The response includes the workflow topology, node states, and execution progress of each step.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/uidParam'
responses:
'200':
description: Workflow details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
put:
operationId: updateWorkflow
summary: Chaos Mesh Update a workflow
description: Updates an existing chaos workflow with a new definition. The workflow spec is replaced with the provided Kubernetes object description.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/uidParam'
requestBody:
description: Updated workflow custom resource definition.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KubeObjectDesc'
responses:
'200':
description: Workflow updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteWorkflow
summary: Chaos Mesh Delete a workflow
description: Deletes a specific chaos workflow by its UID. The workflow and all its associated Kubernetes resources are removed.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/uidParam'
responses:
'200':
description: Workflow deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/workflows/parse-task/http:
post:
operationId: parseWorkflowHttpTask
summary: Chaos Mesh Parse an HTTP workflow task
description: Parses a rendered HTTP workflow task template back to the original request form. Used by the UI to convert between internal representations and editable form data for HTTP tasks in workflows.
tags:
- Workflows
requestBody:
description: Rendered HTTP task template to parse.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
responses:
'200':
description: Task parsed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/HttpRequestForm'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/workflows/render-task/http:
post:
operationId: renderWorkflowHttpTask
summary: Chaos Mesh Render an HTTP workflow task
description: Renders an HTTP workflow task from a request form into the final template format used in workflow definitions. This converts the UI form submission into the internal Template representation.
tags:
- Workflows
requestBody:
description: HTTP task request form to render.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HttpRequestForm'
responses:
'200':
description: Task rendered successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/workflows/validate-task/http:
post:
operationId: validateWorkflowHttpTask
summary: Chaos Mesh Validate an HTTP workflow task
description: Validates that a given rendered Template is a valid HTTP task. Returns true if the template is valid, false or an error if it is not.
tags:
- Workflows
requestBody:
description: Rendered template to validate.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
responses:
'200':
description: Validation result returned.
content:
application/json:
schema:
type: boolean
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
/api/workflows:
get:
operationId: listWorkflows
summary: Chaos Mesh List workflows
description: Returns a list of Chaos Mesh workflows. Workflows allow orchestrating multiple chaos experiments in serial or parallel sequences. Results can be filtered by namespace, name, and status.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/NamespaceQuery'
- $ref: '#/components/parameters/NameQuery'
- $ref: '#/components/parameters/StatusQuery'
responses:
'200':
description: List of workflows
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkflowSummary'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
post:
operationId: createWorkflow
summary: Chaos Mesh Create a workflow
description: Creates a new Chaos Mesh workflow for orchestrating multiple chaos experiments. The workflow spec defines a directed acyclic graph of tasks that can run in serial, parallel, or with suspend steps. Each task can reference a chaos template or be a sub-workflow.
tags:
- Workflows
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowCreateRequest'
responses:
'200':
description: Workflow created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail_2'
'400':
$ref: '#/components/responses/BadRequest_2'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/workflows/{uid}:
get:
operationId: getWorkflow
summary: Chaos Mesh Get a workflow
description: Returns detailed information about a specific workflow including its current execution state, the status of each task node, and associated event history.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/WorkflowUID'
responses:
'200':
description: Workflow details
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail_2'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound_2'
'500':
$ref: '#/components/responses/InternalError'
put:
operationId: updateWorkflow
summary: Chaos Mesh Update a workflow
description: Updates an existing workflow definition. The updated spec replaces the existing workflow configuration. Running workflow nodes are not interrupted; changes take effect on future executions.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/WorkflowUID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowCreateRequest'
responses:
'200':
description: Workflow updated
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowDetail_2'
'400':
$ref: '#/components/responses/BadRequest_2'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound_2'
delete:
operationId: deleteWorkflow
summary: Chaos Mesh Delete a workflow
description: Deletes a Chaos Mesh workflow and stops any running chaos tasks within it. The deleted workflow is moved to the archives.
tags:
- Workflows
parameters:
- $ref: '#/components/parameters/WorkflowUID'
responses:
'200':
description: Workflow deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound_2'
components:
schemas:
StatusResponse:
type: object
description: Generic status response for operations that do not return a resource.
properties:
status:
type: string
description: Status of the operation (e.g., success).
Topology:
type: object
description: Workflow execution topology showing nodes and their states.
properties:
nodes:
type: array
description: List of workflow nodes representing individual steps.
items:
$ref: '#/components/schemas/Node'
WorkflowMeta:
type: object
description: Summary metadata for a Chaos Mesh workflow.
properties:
uid:
type: string
format: uuid
description: Unique identifier of the workflow.
name:
type: string
description: Name of the workflow Kubernetes resource.
namespace:
type: string
description: Kubernetes namespace of the workflow.
entry:
type: string
description: Name of the entry template in the workflow.
created_at:
type: string
format: date-time
description: Timestamp when the workflow was created.
end_time:
type: string
format: date-time
description: Timestamp when the workflow finished, if applicable.
status:
type: string
description: Current status of the workflow.
APIError:
type: object
description: Error response returned when an API request fails.
required:
- code
- message
properties:
code:
type: integer
description: HTTP status code of the error.
message:
type: string
description: Human-readable description of the error.
full_text:
type: string
description: Full error text including stack trace or detailed cause.
ErrorResponse:
type: object
description: Error response returned when an API operation fails.
properties:
code:
type: integer
description: HTTP status code.
example: 404
message:
type: string
description: Human-readable error message.
example: experiment not found
Node:
type: object
description: A node in the workflow topology representing a single execution step.
properties:
name:
type: string
description: Name of the workflow node.
uid:
type: string
description: UID of the workflow node.
type:
type: string
description: Type of workflow node (e.g., ChaosNode, SerialNode, ParallelNode, SuspendNode, TaskNode).
state:
type: string
description: Execution state of the node (e.g., Running, Succeeded, Failed, Pending).
template:
type: string
description: Template name this node is executing.
serial:
type: boolean
description: Whether this node is executing in serial order.
WorkflowDetail_2:
type: object
description: Full details of a Chaos Mesh workflow including spec and node status.
properties:
uid:
type: string
format: uuid
description: Unique identifier for the workflow.
namespace:
type: string
description: Kubernetes namespace of the workflow.
name:
type: string
description: Name of the workflow resource.
spec:
type: object
description: Full workflow specification as a Kubernetes custom resource spec.
additionalProperties: true
status:
type: string
description: Overall execution status.
topology:
type: object
description: Execution graph topology showing the current state of each task node in the workflow.
additionalProperties: true
Template:
type: object
description: A workflow template defining a single step or group in a chaos workflow.
properties:
name:
type: string
description: Unique name of the template within the workflow.
templateType:
type: string
description: Type of the template (e.g., Task, Serial, Parallel, Suspend, Schedule).
deadline:
type: string
description: Maximum duration for this template step.
task:
type: object
description: Task-specific configuration for HTTP or chaos tasks.
additionalProperties: true
children:
type: array
description: Child template names for serial or parallel groups.
items:
type: string
conditionalBranches:
type: array
description: Conditional branches for workflow decision points.
items:
$ref: '#/components/schemas/ConditionalBranch'
HttpRequestForm:
type: object
description: Form representation of an HTTP workflow task for use in the UI.
properties:
url:
type: string
format: uri
description: Target URL for the HTTP request.
method:
type: string
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
- HEAD
description: HTTP method to use.
headers:
type: object
description: HTTP headers to include in the request.
additionalProperties:
type: string
body:
type: string
description: Request body content.
follow_redirects:
type: boolean
description: Whether to follow HTTP redirects.
timeout:
type: string
description: Request timeout duration.
KubeObjectDesc:
type: object
description: A Kubernetes object description used to represent chaos custom resources. Contains the full spec of a Kubernetes resource including apiVersion, kind, metadata, and spec.
properties:
apiVersion:
type: string
description: Kubernetes API version (e.g., chaos-mesh.org/v1alpha1).
kind:
type: string
description: Kubernetes resource kind (e.g., PodChaos, NetworkChaos).
metadata:
$ref: '#/components/schemas/KubeObjectMeta'
spec:
type: object
description: Resource-specific spec object containing the chaos configuration.
additionalProperties: true
WorkflowDetail:
type: object
description: Detailed information about a chaos workflow including node topology.
properties:
uid:
type: string
format: uuid
description: Unique identifier of the workflow.
name:
type: string
description: Name of the workflow.
namespace:
type: string
description: Kubernetes namespace of the workflow.
entry:
type: string
description: Entry point template name for the workflow.
created_at:
type: string
format: date-time
description: Timestamp when the workflow was created.
end_time:
type: string
format: date-time
description: Timestamp when the workflow finished.
status:
type: string
description: Current status of the workflow.
topology:
$ref: '#/components/schemas/Topology'
kube_object:
$ref: '#/components/schemas/KubeObjectDesc'
WorkflowSummary:
type: object
description: Summary of a Chaos Mesh workflow as returned in list operations.
properties:
uid:
type: string
format: uuid
description: Unique identifier for the workflow.
namespace:
type: string
description: Kubernetes namespace of the workflow.
name:
type: string
description: Name of the workflow resource.
example: resilience-test-workflow
entry:
type: string
description: Entry point task name for the workflow graph.
status:
type: string
description: Overall execution status of the workflow.
created_at:
type: string
format: date-time
description: Timestamp when the workflow was created.
end_time:
type: string
format: date-time
description: Timestamp when the workflow completed, if finished.
ConditionalBranch:
type: object
description: A conditional branch in a workflow that executes based on an expression.
properties:
target:
type: string
description: Name of the template to execute if the condition is true.
expression:
type: string
description: Boolean expression that determines whether to take this branch.
KubeObjectMeta:
type: object
description: Kubernetes object metadata fields.
properties:
name:
type: string
description: Name of the Kubernetes resource.
namespace:
type: string
description: Kubernetes namespace of the resource.
labels:
type: object
description: Labels applied to the resource.
additionalProperties:
type: string
annotations:
type: object
description: Annotations applied to the resource.
additionalProperties:
type: string
WorkflowCreateRequest:
type: object
description: Request body for creating or updating a Chaos Mesh workflow.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
const: chaos-mesh.org/v1alpha1
description: Chaos Mesh API version.
kind:
type: string
const: Workflow
description: Resource kind identifier.
metadata:
type: object
description: Kubernetes object metadata.
required:
- name
- namespace
properties:
name:
type: string
description: Name of the workflow resource.
namespace:
type: string
description: Kubernetes namespace for the workflow.
spec:
type: object
description: Workflow specification defining the entry point, templates, and task graph.
required:
- entry
- templates
properties:
entry:
type: string
description: Name of the entry point template in the workflow.
templates:
type: array
description: List of workflow task templates defining chaos experiments, suspend steps, serial sequences, or parallel groups.
items:
type: object
additionalProperties: true
responses:
BadRequest:
description: Bad request — invalid parameters or request body.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
NotFound_2:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest_2:
description: Bad request — invalid parameters or malformed body
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Unauthorized — authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
parameters:
NameQuery:
name: name
in: query
required: false
description: Name substring to filter results by.
schema:
type: string
StatusQuery:
name: status
in: query
required: false
description: Status to filter experiments or schedules by.
schema:
type: string
enum:
- injecting
- running
- finished
- paused
- stopped
uidParam:
name: uid
in: path
description: UUID of the chaos resource.
required: true
schema:
type: string
format: uuid
namespaceParam:
name: namespace
in: query
description: Kubernetes namespace to scope the request to.
required: false
schema:
type: string
NamespaceQuery:
name: namespace
in: query
required: false
description: Kubernetes namespace to filter results by. If omitted, returns results from all namespaces.
schema:
type: string
example: default
WorkflowUID:
name: uid
in: path
required: true
description: Unique identifier (UUID) of the workflow.
schema:
type: string
format: uuid
externalDocs:
description: Chaos Mesh Documentation
url: https://chaos-mesh.org/docs/