openapi: 3.1.0
info:
  title: CubeFS Master ACLs DataNodes API
  description: The CubeFS Master API provides HTTP endpoints for administering a CubeFS distributed storage cluster. The Master node is the control plane for all cluster operations including volume lifecycle management, data and metadata node administration, user and access key management, and cluster health monitoring. All endpoints are served over HTTP on the Master node's listen port (default 17010) and accept query string parameters. Responses are JSON objects with a code field indicating success (200) or error.
  version: '3.3'
  contact:
    name: CubeFS Community
    url: https://cubefs.io/community/overview.html
servers:
- url: http://{masterHost}:{masterPort}
  description: CubeFS Master node HTTP API server
  variables:
    masterHost:
      default: 127.0.0.1
      description: IP address or hostname of the CubeFS Master node.
    masterPort:
      default: '17010'
      description: Listening port of the CubeFS Master node.
tags:
- name: DataNodes
  description: Data node management operations including listing nodes, querying node status, decommissioning nodes, and managing data partitions on nodes.
paths:
  /dataNode/add:
    get:
      operationId: addDataNode
      summary: CubeFS Add a data node
      description: Registers a new data node with the cluster at the specified address. The data node must already be running and accessible at the given address before it can be added to the cluster.
      tags:
      - DataNodes
      parameters:
      - name: addr
        in: query
        required: true
        description: Address of the data node in host:port format.
        schema:
          type: string
      responses:
        '200':
          description: Data node added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /dataNode/get:
    get:
      operationId: getDataNode
      summary: CubeFS Get data node information
      description: Returns detailed information about a specific data node including its address, status, available capacity, used capacity, data partition list, and disk information.
      tags:
      - DataNodes
      parameters:
      - name: addr
        in: query
        required: true
        description: Address of the data node in host:port format.
        schema:
          type: string
      responses:
        '200':
          description: Data node information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataNodeInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dataNode/decommission:
    get:
      operationId: decommissionDataNode
      summary: CubeFS Decommission a data node
      description: Removes a data node from the cluster. All data partitions on the node are asynchronously migrated to other available data nodes before the node is fully removed. This is a safe operation for draining a node during maintenance or replacement.
      tags:
      - DataNodes
      parameters:
      - name: addr
        in: query
        required: true
        description: Address of the data node to decommission in host:port format.
        schema:
          type: string
      responses:
        '200':
          description: Data node decommission initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response from the CubeFS Master API.
      properties:
        code:
          type: integer
          description: Error code. Non-200 values indicate failure.
        msg:
          type: string
          description: Human-readable error message.
        data:
          description: Additional error context, may be null or empty.
    DataNodeInfoResponse:
      type: object
      description: Detailed data node information response.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message.
        data:
          type: object
          description: Data node details.
          properties:
            Addr:
              type: string
              description: Address of the data node.
            Status:
              type: boolean
              description: Whether the node is active.
            TotalWeight:
              type: integer
              description: Total storage capacity in bytes.
            UsedWeight:
              type: integer
              description: Used storage in bytes.
            AvailableSpace:
              type: integer
              description: Available storage in bytes.
            DataPartitionCount:
              type: integer
              description: Number of data partitions on this node.
            DataPartitionReports:
              type: array
              description: Reports for each data partition on this node.
              items:
                type: object
                description: Data partition report from this node.
    GeneralResponse:
      type: object
      description: General success response from the CubeFS Master API.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message, typically "success".
        data:
          description: Response data, content varies by operation.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
externalDocs:
  description: CubeFS Master Admin API Reference
  url: https://cubefs.io/docs/master/dev-guide/admin-api/master/