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/