openapi: 3.1.0
info:
  title: CubeFS Master ACLs DataPartitions 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: DataPartitions
  description: Data partition management including creating, loading, decommissioning, and diagnosing data partitions within volumes.
paths:
  /dataPartition/create:
    get:
      operationId: createDataPartition
      summary: CubeFS Create a data partition
      description: Manually creates a data partition for a specific volume. This is typically done automatically by the Master when volume usage exceeds thresholds, but can be triggered manually when the cluster is frozen or for operational purposes.
      tags:
      - DataPartitions
      parameters:
      - name: count
        in: query
        required: true
        description: Number of data partitions to create.
        schema:
          type: integer
          minimum: 1
      - name: name
        in: query
        required: true
        description: Name of the volume to create data partitions for.
        schema:
          type: string
      responses:
        '200':
          description: Data partitions created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /dataPartition/decommission:
    get:
      operationId: decommissionDataPartition
      summary: CubeFS Decommission a data partition
      description: Migrates a specific data partition from a given data node to another available data node. Used to drain a node before decommissioning or to rebalance data distribution.
      tags:
      - DataPartitions
      parameters:
      - name: id
        in: query
        required: true
        description: ID of the data partition to decommission.
        schema:
          type: integer
      - name: addr
        in: query
        required: true
        description: Address of the data node hosting the partition to migrate away from.
        schema:
          type: string
      responses:
        '200':
          description: Data partition decommission initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
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.
    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:
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      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/