openapi: 3.1.0
info:
  title: CubeFS Master ACLs Volumes 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: Volumes
  description: Volume lifecycle management operations including creating, updating, expanding, shrinking, and deleting volumes. Volumes are the top-level storage namespaces in CubeFS.
paths:
  /admin/createVol:
    get:
      operationId: createVolume
      summary: CubeFS Create a volume
      description: Creates a new CubeFS volume with the specified configuration. Volumes are the top-level namespace for storing data. When created, CubeFS allocates 10 data partitions and 3 metadata partitions by default. If no user matching the owner ID exists, a new user is automatically created with that ID. The volume can be configured for replication or erasure coding.
      tags:
      - Volumes
      parameters:
      - name: name
        in: query
        required: true
        description: Unique name for the new volume.
        schema:
          type: string
      - name: capacity
        in: query
        required: true
        description: Capacity of the volume in GB.
        schema:
          type: integer
          minimum: 1
      - name: owner
        in: query
        required: true
        description: User ID that owns this volume. Creates the user if they do not exist.
        schema:
          type: string
      - name: mpCount
        in: query
        required: false
        description: Initial number of metadata partitions. Defaults to 3.
        schema:
          type: integer
          minimum: 1
      - name: dpCount
        in: query
        required: false
        description: Initial number of data partitions. Defaults to 10.
        schema:
          type: integer
          minimum: 1
      - name: replicaNum
        in: query
        required: false
        description: Replication factor for data partitions. Defaults to 3.
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
      - name: followerRead
        in: query
        required: false
        description: Whether follower replicas can serve read requests.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: enablePosixAcl
        in: query
        required: false
        description: Whether POSIX ACL is enabled for this volume.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: volType
        in: query
        required: false
        description: Volume type. 0 for replicated, 1 for erasure coded.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: qosEnable
        in: query
        required: false
        description: Whether QoS (quality of service) throttling is enabled.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Volume created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /admin/getVol:
    get:
      operationId: getVolume
      summary: CubeFS Get volume information
      description: Returns detailed information about a specific volume including its name, owner, capacity, replication configuration, data partition list, metadata partition list, and current status.
      tags:
      - Volumes
      parameters:
      - name: name
        in: query
        required: true
        description: Name of the volume to retrieve.
        schema:
          type: string
      - name: authKey
        in: query
        required: true
        description: MD5 of the owner's user ID for authentication.
        schema:
          type: string
      responses:
        '200':
          description: Volume information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /admin/listVols:
    get:
      operationId: listVolumes
      summary: CubeFS List volumes
      description: Returns a list of all volumes in the cluster. The results can be filtered by keyword to match volume names containing the specified substring.
      tags:
      - Volumes
      parameters:
      - name: keywords
        in: query
        required: false
        description: Substring filter for volume names.
        schema:
          type: string
      responses:
        '200':
          description: Volume list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vol/update:
    get:
      operationId: updateVolume
      summary: CubeFS Update volume configuration
      description: Updates configuration parameters for an existing volume including capacity, replication settings, QoS parameters, follower read policy, and access control settings.
      tags:
      - Volumes
      parameters:
      - name: name
        in: query
        required: true
        description: Name of the volume to update.
        schema:
          type: string
      - name: authKey
        in: query
        required: true
        description: MD5 of the owner's user ID for authentication.
        schema:
          type: string
      - name: capacity
        in: query
        required: false
        description: New capacity in GB for the volume.
        schema:
          type: integer
          minimum: 1
      - name: followerRead
        in: query
        required: false
        description: Enable or disable follower reads.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: replicaNum
        in: query
        required: false
        description: New replication factor for the volume.
        schema:
          type: integer
      - name: enablePosixAcl
        in: query
        required: false
        description: Enable or disable POSIX ACL.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Volume updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /vol/delete:
    get:
      operationId: deleteVolume
      summary: CubeFS Delete a volume
      description: Marks a volume for deletion. The volume is first logically deleted by setting its status to deleted, then all data and metadata partitions are asynchronously removed via periodic tasks. Erasure-coded volumes can only be deleted when their used size is 0.
      tags:
      - Volumes
      parameters:
      - name: name
        in: query
        required: true
        description: Name of the volume to delete.
        schema:
          type: string
      - name: authKey
        in: query
        required: true
        description: MD5 of the owner's user ID for authentication.
        schema:
          type: string
      responses:
        '200':
          description: Volume deletion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /vol/expand:
    get:
      operationId: expandVolume
      summary: CubeFS Expand volume capacity
      description: Expands the storage capacity of a volume to the specified size in GB. The new capacity must be larger than the current capacity. CubeFS will automatically allocate additional data partitions as needed.
      tags:
      - Volumes
      parameters:
      - name: name
        in: query
        required: true
        description: Name of the volume to expand.
        schema:
          type: string
      - name: authKey
        in: query
        required: true
        description: MD5 of the owner's user ID for authentication.
        schema:
          type: string
      - name: capacity
        in: query
        required: true
        description: New capacity in GB. Must be greater than current capacity.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Volume expansion 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.
    VolumeInfoResponse:
      type: object
      description: Detailed volume information response.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message.
        data:
          $ref: '#/components/schemas/VolumeInfo'
    DataPartitionView:
      type: object
      description: Summary of a data partition.
      properties:
        PartitionID:
          type: integer
          description: Unique partition identifier.
        Status:
          type: integer
          description: Partition status.
        ReplicaNum:
          type: integer
          description: Number of replicas for this partition.
        Hosts:
          type: array
          description: Data nodes hosting replicas of this partition.
          items:
            type: string
            description: Node address in host:port format.
    VolumeView:
      type: object
      description: Summary view of a CubeFS volume.
      properties:
        Name:
          type: string
          description: Name of the volume.
        Owner:
          type: string
          description: User ID that owns the volume.
        CreateTime:
          type: string
          description: Volume creation timestamp.
        Status:
          type: integer
          description: Volume status. 0 is normal, 1 is marked for deletion.
        TotalSize:
          type: integer
          description: Total capacity allocated to the volume in bytes.
        UsedSize:
          type: integer
          description: Amount of storage used in bytes.
        DpCnt:
          type: integer
          description: Number of data partitions.
        MpCnt:
          type: integer
          description: Number of metadata partitions.
    MetaPartitionView:
      type: object
      description: Summary of a metadata partition.
      properties:
        PartitionID:
          type: integer
          description: Unique partition identifier.
        Start:
          type: integer
          description: Start of the inode range for this partition.
        End:
          type: integer
          description: End of the inode range for this partition.
        InodeCount:
          type: integer
          description: Current number of inodes in this partition.
        MaxInodeID:
          type: integer
          description: Highest inode ID in this partition.
        IsRecover:
          type: boolean
          description: Whether this partition is currently recovering.
        Hosts:
          type: array
          description: Metadata nodes hosting this partition.
          items:
            type: string
            description: Node address in host:port format.
    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.
    VolumeListResponse:
      type: object
      description: List of volumes response.
      properties:
        code:
          type: integer
          description: Response code. 200 indicates success.
        msg:
          type: string
          description: Response message.
        data:
          type: array
          description: List of volume summary objects.
          items:
            $ref: '#/components/schemas/VolumeView'
    VolumeInfo:
      type: object
      description: Detailed information about a CubeFS volume.
      properties:
        Name:
          type: string
          description: Name of the volume.
        Owner:
          type: string
          description: User ID that owns the volume.
        Capacity:
          type: integer
          description: Total configured capacity in GB.
        ReplicaNum:
          type: integer
          description: Replication factor for data partitions.
        FollowerRead:
          type: boolean
          description: Whether follower replicas can serve reads.
        Status:
          type: integer
          description: Volume status. 0 is normal, 1 is marked for deletion.
        EnablePosixAcl:
          type: boolean
          description: Whether POSIX ACL is enabled.
        VolType:
          type: integer
          description: Volume type. 0 for replicated, 1 for erasure coded.
        DataPartitions:
          type: array
          description: List of data partitions belonging to this volume.
          items:
            $ref: '#/components/schemas/DataPartitionView'
        MetaPartitions:
          type: array
          description: List of metadata partitions belonging to this volume.
          items:
            $ref: '#/components/schemas/MetaPartitionView'
  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/