tidb Clusters API

openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Clusters API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing API Server
security:
- digestAuth: []
tags:
- name: Clusters
  description: Operations for creating, listing, updating, and deleting TiDB Cloud Dedicated clusters.
paths:
  /clusters:
    get:
      operationId: listClusters
      summary: List clusters
      description: Returns a paginated list of TiDB Cloud Dedicated clusters within the organization or a specific project. Supports filtering by project ID, region, and cluster state. Results are paginated using page tokens.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      - name: projectId
        in: query
        description: Filter clusters by project ID.
        required: false
        schema:
          type: string
      - name: clusterStates
        in: query
        description: Filter clusters by state. Possible values include CREATING, ACTIVE, PAUSED, RESUMING, DELETING, and UPGRADING.
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A paginated list of clusters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClustersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createCluster
      summary: Create a cluster
      description: Creates a new TiDB Cloud Dedicated cluster within the specified project. The request body must specify the cluster name, cloud provider, region, and component configuration including TiDB, TiKV, and optionally TiFlash node sizes and counts. Use validateOnly to test a request without actually creating the cluster.
      tags:
      - Clusters
      parameters:
      - name: validateOnly
        in: query
        description: If true, validates the request without creating the cluster.
        required: false
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClusterRequest'
      responses:
        '200':
          description: Cluster created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /clusters/{clusterId}:
    get:
      operationId: getCluster
      summary: Get a cluster
      description: Returns the full configuration and current status of a specific TiDB Cloud Dedicated cluster, including its nodes, network configuration, version, and operational state.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCluster
      summary: Update a cluster
      description: Modifies the configuration of an existing TiDB Cloud Dedicated cluster. Supports scaling TiDB node count, TiKV storage size, and TiFlash node count. Only fields included in the request body are updated; omitted fields remain unchanged.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClusterRequest'
      responses:
        '200':
          description: Cluster updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCluster
      summary: Delete a cluster
      description: Permanently deletes a TiDB Cloud Dedicated cluster and all associated data. This operation is irreversible. The cluster must be in an active or paused state before deletion.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster deletion initiated successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /clusters/{clusterId}:pauseCluster:
    post:
      operationId: pauseCluster
      summary: Pause a cluster
      description: Pauses a running TiDB Cloud Dedicated cluster, suspending compute resources while retaining data in storage. Paused clusters do not incur compute charges. The cluster must be in an ACTIVE state to be paused.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster pause initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /clusters/{clusterId}:resumeCluster:
    post:
      operationId: resumeCluster
      summary: Resume a cluster
      description: Resumes a paused TiDB Cloud Dedicated cluster, restoring compute resources and making the cluster available for connections. The cluster must be in a PAUSED state to be resumed.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster resume initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /clusters/{clusterId}:resetRootPassword:
    post:
      operationId: resetClusterRootPassword
      summary: Reset root password
      description: Resets the root password for a TiDB Cloud Dedicated cluster. The new password is specified in the request body. After the reset, existing connections using the old password will be invalidated.
      tags:
      - Clusters
      parameters:
      - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - password
              properties:
                password:
                  type: string
                  description: The new root password for the cluster.
      responses:
        '200':
          description: Root password reset successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateClusterRequest:
      type: object
      description: Request body for updating a TiDB Cloud Dedicated cluster configuration.
      properties:
        displayName:
          type: string
          description: The new display name for the cluster.
        components:
          $ref: '#/components/schemas/ClusterComponents'
    ListClustersResponse:
      type: object
      description: Paginated list of TiDB Cloud clusters.
      properties:
        clusters:
          type: array
          description: The list of cluster objects on this page.
          items:
            $ref: '#/components/schemas/Cluster'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results. Empty if on the last page.
    ClusterComponents:
      type: object
      description: The component configuration for a TiDB Cloud cluster.
      properties:
        tidb:
          $ref: '#/components/schemas/ComponentSpec'
        tikv:
          $ref: '#/components/schemas/StorageComponentSpec'
        tiflash:
          $ref: '#/components/schemas/StorageComponentSpec'
    ConnectionStrings:
      type: object
      description: Connection string information for connecting to the cluster.
      properties:
        defaultUser:
          type: string
          description: The default database user for the cluster.
        standard:
          $ref: '#/components/schemas/ConnectionString'
        vpcPeering:
          $ref: '#/components/schemas/ConnectionString'
        privateEndpoint:
          $ref: '#/components/schemas/ConnectionString'
    ComponentSpec:
      type: object
      description: Specification for a stateless TiDB compute node group.
      properties:
        nodeSize:
          type: string
          description: The node size key identifying the CPU and memory configuration.
        nodeQuantity:
          type: integer
          description: The number of nodes in this component group.
    ErrorResponse:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: The HTTP status code of the error.
        status:
          type: string
          description: The error status string.
        error:
          type: string
          description: A machine-readable error code identifier.
        msgPrefix:
          type: string
          description: A human-readable error message describing the failure.
    StorageComponentSpec:
      type: object
      description: Specification for a TiKV or TiFlash storage node group.
      properties:
        nodeSize:
          type: string
          description: The node size key identifying the CPU and memory configuration.
        nodeQuantity:
          type: integer
          description: The number of nodes in this component group.
        storageSize:
          type: integer
          description: The storage capacity per node in GiB.
    Cluster:
      type: object
      description: A TiDB Cloud Dedicated cluster resource.
      properties:
        clusterId:
          type: string
          description: The unique identifier of the cluster.
        displayName:
          type: string
          description: The human-readable display name of the cluster.
        clusterType:
          type: string
          description: The cluster type, always DEDICATED for dedicated clusters.
          enum:
          - DEDICATED
        cloudProvider:
          type: string
          description: The cloud provider hosting the cluster (AWS, GCP, or Azure).
          enum:
          - AWS
          - GCP
          - AZURE
        regionId:
          type: string
          description: The region identifier where the cluster is deployed.
        tidbVersion:
          type: string
          description: The TiDB database version running on the cluster.
        state:
          type: string
          description: The current operational state of the cluster.
          enum:
          - CREATING
          - ACTIVE
          - PAUSED
          - RESUMING
          - DELETING
          - UPGRADING
          - MODIFYING
        createTime:
          type: string
          format: date-time
          description: The timestamp when the cluster was created.
        updateTime:
          type: string
          format: date-time
          description: The timestamp when the cluster was last modified.
        components:
          $ref: '#/components/schemas/ClusterComponents'
        connectionStrings:
          $ref: '#/components/schemas/ConnectionStrings'
    CreateClusterRequest:
      type: object
      description: Request body for creating a new TiDB Cloud Dedicated cluster.
      required:
      - displayName
      - cloudProvider
      - regionId
      - components
      properties:
        displayName:
          type: string
          description: The display name for the new cluster.
        projectId:
          type: string
          description: The project ID to create the cluster in. Defaults to the default project.
        cloudProvider:
          type: string
          description: The cloud provider for the cluster.
          enum:
          - AWS
          - GCP
          - AZURE
        regionId:
          type: string
          description: The region identifier where the cluster will be deployed.
        components:
          $ref: '#/components/schemas/ClusterComponents'
        rootPassword:
          type: string
          description: The initial root password for the cluster.
        port:
          type: integer
          description: The SQL connection port. Default is 4000.
    ConnectionString:
      type: object
      description: A specific type of connection string for accessing the cluster.
      properties:
        host:
          type: string
          description: The hostname for the connection.
        port:
          type: integer
          description: The TCP port number for the connection.
  parameters:
    clusterId:
      name: clusterId
      in: path
      description: The unique identifier of the TiDB Cloud Dedicated cluster.
      required: true
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of results to return per page. Default is 100, maximum is 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    pageToken:
      name: pageToken
      in: query
      description: Pagination token returned from a previous list request to retrieve the next page.
      required: false
      schema:
        type: string
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed. Check your API key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: Rate limit exceeded. The API allows 100 requests per minute.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud API public key as the username and private key as the password. Keys are generated in the TiDB Cloud console under Organization Settings > API Keys.
externalDocs:
  description: TiDB Cloud API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/