Chaos Mesh Common API

openapi: 3.2.0
info:
  title: Chaos Mesh Common API
  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
  version: '1.0'
  description: 'Operations tagged Common across 2 of this provider''s published API definitions: chaos-mesh-dashboard-api-openapi.yml, chaos-mesh-dashboard-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:2333/api
  description: Default Chaos Mesh Dashboard server
- url: http://{dashboardHost}:{dashboardPort}
  description: Chaos Mesh Dashboard API server
  variables:
    dashboardHost:
      default: chaos-dashboard.chaos-testing
      description: Hostname or service name for the Chaos Mesh Dashboard.
    dashboardPort:
      default: '2333'
      description: Port on which the Chaos Mesh Dashboard API listens.
tags:
- name: Common
  description: Utility endpoints for cluster metadata, namespaces, and configuration
paths:
  /common/config:
    get:
      operationId: getDashboardConfig
      summary: Chaos Mesh Get Dashboard configuration
      description: Returns the current configuration of the Chaos Mesh Dashboard including security settings, namespace scope, and feature flags.
      tags:
      - Common
      responses:
        '200':
          description: Dashboard configuration returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardConfig'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/namespaces:
    get:
      operationId: listNamespaces
      summary: Chaos Mesh Get all Kubernetes namespaces
      description: Returns a list of all namespace names from the Kubernetes cluster. Used by the UI for namespace selection dropdowns when scoping experiments.
      tags:
      - Common
      responses:
        '200':
          description: List of namespaces returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Kubernetes namespace name.
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/chaos-available-namespaces:
    get:
      operationId: listChaosAvailableNamespaces
      summary: Chaos Mesh Get namespaces available for chaos injection
      description: Returns the list of namespaces where chaos can be injected based on Chaos Mesh RBAC configuration and namespace scope settings.
      tags:
      - Common
      responses:
        '200':
          description: List of available namespaces returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Kubernetes namespace name.
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/kinds:
    get:
      operationId: listChaosKinds
      summary: Chaos Mesh Get all available chaos kinds
      description: Returns a list of all chaos experiment kinds available in the current Kubernetes cluster based on installed CRDs. Examples include PodChaos, NetworkChaos, IOChaos, StressChaos, TimeChaos, HTTPChaos, and cloud provider chaos types.
      tags:
      - Common
      responses:
        '200':
          description: List of chaos kinds returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Chaos kind name (Kubernetes CRD kind).
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/labels:
    get:
      operationId: getPodLabels
      summary: Chaos Mesh Get pod labels
      description: Returns a map of label keys to their possible values for pods in the specified namespace. Used by the UI to build label selector inputs for targeting experiments at specific pods.
      tags:
      - Common
      parameters:
      - $ref: '#/components/parameters/namespaceParam'
      responses:
        '200':
          description: Pod labels returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapStringSliceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/annotations:
    get:
      operationId: getPodAnnotations
      summary: Chaos Mesh Get pod annotations
      description: Returns a map of annotation keys to their possible values for pods in the specified namespace.
      tags:
      - Common
      parameters:
      - $ref: '#/components/parameters/namespaceParam'
      responses:
        '200':
          description: Pod annotations returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapStringSliceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/pods:
    post:
      operationId: listPods
      summary: Chaos Mesh List pods matching a selector
      description: Returns pods from the Kubernetes cluster that match the provided label selector. Used by the UI to preview which pods would be targeted by an experiment before creating it.
      tags:
      - Common
      requestBody:
        description: Label selector to filter pods.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectorRequest'
      responses:
        '200':
          description: Matching pods returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pod'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/physicalmachines:
    post:
      operationId: listPhysicalMachines
      summary: Chaos Mesh List physical machines matching a selector
      description: Returns PhysicalMachine resources from the Kubernetes cluster that match the provided selector. Physical machines are used for chaos experiments targeting bare-metal or VM hosts via the chaos-daemon.
      tags:
      - Common
      requestBody:
        description: Selector to filter physical machines.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectorRequest'
      responses:
        '200':
          description: Matching physical machines returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PhysicalMachine'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /common/rbac-config:
    get:
      operationId: getRbacConfig
      summary: Chaos Mesh Get RBAC configuration
      description: Returns the RBAC configuration guidance for setting up Chaos Mesh permissions. This endpoint helps users understand what RBAC roles and bindings are needed to run chaos experiments in their chosen namespace with their chosen scope.
      tags:
      - Common
      parameters:
      - $ref: '#/components/parameters/namespaceParam'
      - name: role
        in: query
        description: Role type to generate RBAC config for (manager or viewer).
        required: false
        schema:
          type: string
          enum:
          - manager
          - viewer
      - name: scope
        in: query
        description: Scope of the RBAC config (cluster or namespace).
        required: false
        schema:
          type: string
          enum:
          - cluster
          - namespace
      responses:
        '200':
          description: RBAC configuration returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapStringSliceResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: http://localhost:2333/api
      description: Default Chaos Mesh Dashboard server
  /api/common/namespaces:
    get:
      operationId: listNamespaces
      summary: Chaos Mesh List namespaces
      description: Returns the list of Kubernetes namespaces available for targeting chaos experiments. Used to populate namespace selectors in the Chaos Dashboard UI.
      tags:
      - Common
      responses:
        '200':
          description: List of namespace names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Kubernetes namespace name.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
    servers:
    - url: http://{dashboardHost}:{dashboardPort}
      description: Chaos Mesh Dashboard API server
      variables:
        dashboardHost:
          default: chaos-dashboard.chaos-testing
          description: Hostname or service name for the Chaos Mesh Dashboard.
        dashboardPort:
          default: '2333'
          description: Port on which the Chaos Mesh Dashboard API listens.
  /api/common/pods:
    post:
      operationId: listPodsForSelector
      summary: Chaos Mesh List pods for a selector
      description: Returns a list of pods matching the given label selectors and namespaces. Used to preview which pods will be affected by a chaos experiment before creating it, so operators can verify their target selector.
      tags:
      - Common
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PodSelectorRequest'
      responses:
        '200':
          description: List of matching pods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PodInfo'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
    servers:
    - url: http://{dashboardHost}:{dashboardPort}
      description: Chaos Mesh Dashboard API server
      variables:
        dashboardHost:
          default: chaos-dashboard.chaos-testing
          description: Hostname or service name for the Chaos Mesh Dashboard.
        dashboardPort:
          default: '2333'
          description: Port on which the Chaos Mesh Dashboard API listens.
components:
  schemas:
    PhysicalMachine:
      type: object
      description: A physical machine or VM registered as a Chaos Mesh target.
      properties:
        name:
          type: string
          description: Name of the PhysicalMachine resource.
        namespace:
          type: string
          description: Kubernetes namespace of the resource.
        address:
          type: string
          description: Network address of the physical machine's chaos-daemon.
    MapStringSliceResponse:
      type: object
      description: A map from string keys to arrays of string values.
      additionalProperties:
        type: array
        items:
          type: string
    DashboardConfig:
      type: object
      description: Configuration settings for the Chaos Mesh Dashboard.
      properties:
        security_mode:
          type: boolean
          description: Whether security mode requiring authentication is enabled.
        dns_server_create:
          type: boolean
          description: Whether Chaos Mesh should create a DNS server for DNS chaos.
        version:
          type: string
          description: Version of Chaos Mesh currently running.
        enable_filter_namespace:
          type: boolean
          description: Whether namespace filtering is enabled for the dashboard.
    Pod:
      type: object
      description: Summary of a Kubernetes pod available for chaos targeting.
      properties:
        name:
          type: string
          description: Pod name.
        namespace:
          type: string
          description: Kubernetes namespace of the pod.
        ip:
          type: string
          description: Pod IP address.
        state:
          type: string
          description: Pod state (e.g., Running, Pending, Succeeded, Failed).
    SelectorRequest:
      type: object
      description: Request body for selecting pods or physical machines by label selectors.
      properties:
        namespace:
          type: string
          description: Kubernetes namespace to search.
        label_selectors:
          type: object
          description: Key-value pairs for label selection.
          additionalProperties:
            type: string
        annotation_selectors:
          type: object
          description: Key-value pairs for annotation selection.
          additionalProperties:
            type: string
    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.
    PodInfo:
      type: object
      description: Information about a Kubernetes pod that could be targeted by a chaos experiment.
      properties:
        name:
          type: string
          description: Name of the pod.
          example: frontend-abc123
        namespace:
          type: string
          description: Kubernetes namespace of the pod.
          example: default
        ip:
          type: string
          description: IP address of the pod.
          format: ipv4
          example: 10.0.0.5
        host:
          type: string
          description: Kubernetes node name where the pod is running.
          example: worker-node-1
        status:
          type: string
          description: Current phase of the pod.
          enum:
          - Pending
          - Running
          - Succeeded
          - Failed
          - Unknown
    PodSelectorRequest:
      type: object
      description: Request body for previewing which pods match a chaos experiment selector before creating the experiment.
      required:
      - namespaces
      - labelSelectors
      properties:
        namespaces:
          type: array
          description: Kubernetes namespaces to search for matching pods.
          items:
            type: string
          example:
          - default
          - production
        labelSelectors:
          type: object
          description: Key-value label selectors to match pods. All specified labels must match.
          additionalProperties:
            type: string
          example:
            app: frontend
        expressionSelectors:
          type: array
          description: Advanced Kubernetes label selector expressions.
          items:
            type: object
            additionalProperties: true
        pods:
          type: object
          description: Explicit pod name lists per namespace for fixed targeting rather than label-based selection.
          additionalProperties:
            type: array
            items:
              type: string
    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
  parameters:
    namespaceParam:
      name: namespace
      in: query
      description: Kubernetes namespace to scope the request to.
      required: false
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request — invalid parameters or request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    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'
    BadRequest_2:
      description: Bad request — invalid parameters or malformed body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authenticating API requests. Typically a Kubernetes service account token with RBAC permissions to read/write Chaos Mesh custom resources in the target namespaces.
externalDocs:
  description: Chaos Mesh Documentation
  url: https://chaos-mesh.org/docs/
x-refined-from:
- chaos-mesh-dashboard-api-openapi.yml
- chaos-mesh-dashboard-openapi.yml