openapi: 3.1.0
info:
title: TiDB Cloud 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/
externalDocs:
description: TiDB Cloud API Overview
url: https://docs.pingcap.com/tidbcloud/api-overview/
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
tags:
- name: API Keys
description: Operations for creating, listing, updating, and deleting TiDB Cloud API keys.
- name: Audit Logs
description: Operations for retrieving organization-level console audit logs.
- name: Billing
description: Operations for retrieving monthly billing summaries, cost details, and usage trends.
- name: Clusters
description: Operations for creating, listing, updating, and deleting TiDB Cloud Dedicated clusters.
- name: Imports
description: Operations for creating and managing data import tasks into TiDB Cloud clusters.
- name: Integrations
description: Operations for managing third-party integrations with TiDB Cloud clusters.
- name: Regions
description: Operations for listing available cloud regions and node specifications.
security:
- digestAuth: []
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'
/regions:
get:
operationId: listRegions
summary: List regions
description: >-
Returns a list of all available cloud provider regions where TiDB Cloud
Dedicated clusters can be deployed. Each region includes cloud provider,
region identifier, display name, and availability status.
tags:
- Regions
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of available regions.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRegionsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/regions/{regionId}:
get:
operationId: getRegion
summary: Get a region
description: >-
Returns detailed information about a specific cloud region, including its
cloud provider, display name, geographic location, and support for
specific TiDB Cloud features.
tags:
- Regions
parameters:
- $ref: '#/components/parameters/regionId'
responses:
'200':
description: Region details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Region'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/regions/{regionId}/nodeSpecs:
get:
operationId: listNodeSpecs
summary: List node specifications
description: >-
Returns all available node specifications for a given region, including
TiDB, TiKV, and TiFlash component types. Each specification includes CPU,
memory, and storage details. Use this endpoint to determine valid node
configurations before creating or scaling a cluster.
tags:
- Regions
parameters:
- $ref: '#/components/parameters/regionId'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of node specifications.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNodeSpecsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/clusters/{clusterId}/imports:
get:
operationId: listImports
summary: List import tasks
description: >-
Returns a paginated list of data import tasks for a specific TiDB Cloud
Dedicated cluster. Each import task includes status, source configuration,
progress information, and timestamps.
tags:
- Imports
parameters:
- $ref: '#/components/parameters/clusterId'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of import tasks.
content:
application/json:
schema:
$ref: '#/components/schemas/ListImportsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createImport
summary: Create an import task
description: >-
Creates a new data import task for a specific TiDB Cloud Dedicated
cluster. Supports importing data from AWS S3, Google Cloud Storage, and
local file uploads in CSV, SQL, Parquet, and Aurora Snapshot formats.
Specify the source type, file format, target database, and any necessary
access credentials.
tags:
- Imports
parameters:
- $ref: '#/components/parameters/clusterId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImportRequest'
responses:
'200':
description: Import task created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/clusters/{clusterId}/imports/{importId}:
get:
operationId: getImport
summary: Get an import task
description: >-
Returns the current status and configuration details of a specific data
import task. Includes progress percentage, estimated completion time,
error messages if any, and source file information.
tags:
- Imports
parameters:
- $ref: '#/components/parameters/clusterId'
- $ref: '#/components/parameters/importId'
responses:
'200':
description: Import task details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Import'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/clusters/{clusterId}/imports/{importId}:cancel:
post:
operationId: cancelImport
summary: Cancel an import task
description: >-
Cancels an in-progress data import task for a specific cluster. Only
import tasks in a RUNNING or PENDING state can be cancelled. Cancelled
tasks cannot be resumed; a new import task must be created.
tags:
- Imports
parameters:
- $ref: '#/components/parameters/clusterId'
- $ref: '#/components/parameters/importId'
responses:
'200':
description: Import task cancelled successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/clusters/{clusterId}/integrations:
get:
operationId: listIntegrations
summary: List integrations
description: >-
Returns all third-party integrations configured for a specific TiDB Cloud
Dedicated cluster. Supported integrations include Datadog, Prometheus,
and other observability platforms.
tags:
- Integrations
parameters:
- $ref: '#/components/parameters/clusterId'
responses:
'200':
description: List of integrations retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListIntegrationsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createIntegration
summary: Create an integration
description: >-
Configures a new third-party integration for a specific TiDB Cloud
Dedicated cluster. The integration type and credentials must be specified
in the request body. Once created, TiDB Cloud will begin sending metrics
and logs to the configured integration endpoint.
tags:
- Integrations
parameters:
- $ref: '#/components/parameters/clusterId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIntegrationRequest'
responses:
'200':
description: Integration created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Integration'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/apikeys:
get:
operationId: listApiKeys
summary: List API keys
description: >-
Returns a paginated list of API keys for the organization or a specific
project. Each key entry includes its display name, access key, role, and
creation time. Secret keys are not returned after initial creation.
tags:
- API Keys
parameters:
- name: projectId
in: query
description: Filter API keys by project ID. Omit for organization-level keys.
required: false
schema:
type: integer
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of API keys.
content:
application/json:
schema:
$ref: '#/components/schemas/ListApiKeysResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createApiKey
summary: Create an API key
description: >-
Creates a new API key with the specified display name, project scope, and
role. The response includes both the public access key and the private
secret key. The secret key is only returned at creation time and cannot
be retrieved afterwards; store it securely.
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyRequest'
responses:
'200':
description: API key created successfully. Save the secret key now as it will not be shown again.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/apikeys/{accessKey}:
get:
operationId: getApiKey
summary: Get an API key
description: >-
Returns the metadata and permissions for a specific API key identified by
its public access key. The private secret key is not returned.
tags:
- API Keys
parameters:
- $ref: '#/components/parameters/accessKey'
responses:
'200':
description: API key details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateApiKey
summary: Update an API key
description: >-
Updates the display name or role of an existing API key. Only the fields
provided in the request body are modified. The access key and secret key
remain unchanged.
tags:
- API Keys
parameters:
- $ref: '#/components/parameters/accessKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiKeyRequest'
responses:
'200':
description: API key updated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteApiKey
summary: Delete an API key
description: >-
Permanently deletes an API key. Once deleted, any requests authenticated
with this key will be rejected. This action cannot be undone.
tags:
- API Keys
parameters:
- $ref: '#/components/parameters/accessKey'
responses:
'200':
description: API key deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/auditLogs:
get:
operationId: listAuditLogs
summary: List audit logs
description: >-
Returns a paginated list of console audit logs for the organization.
Audit logs capture administrative actions such as cluster creation,
deletion, and configuration changes, along with the user email, timestamp,
and result of each action. Supports filtering by time range, event type,
and keyword.
tags:
- Audit Logs
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
- name: startTime
in: query
description: Filter audit logs starting from this ISO 8601 datetime.
required: false
schema:
type: string
format: date-time
- name: endTime
in: query
description: Filter audit logs up to this ISO 8601 datetime.
required: false
schema:
type: string
format: date-time
- name: auditEventTypes
in: query
description: Comma-separated list of event types to filter by.
required: false
schema:
type: string
- name: keyword
in: query
description: Search term to filter audit log entries.
required: false
schema:
type: string
responses:
'200':
description: A paginated list of audit log entries.
content:
application/json:
schema:
$ref: '#/components/schemas/ListAuditLogsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/bills/{billedMonth}:
get:
operationId: getMonthlyBill
summary: Get monthly bill
description: >-
Returns the organization's billing summary for the specified month in
YYYY-MM format. Includes an overview of total charges, a breakdown by
project, and a breakdown by service type such as compute, storage,
and data transfer.
tags:
- Billing
parameters:
- $ref: '#/components/parameters/billedMonth'
responses:
'200':
description: Monthly bill retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BillsExplorer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/billsDetails/{billedMonth}:
get:
operationId: getMonthlyBillDetails
summary: Get monthly bill with daily details
description: >-
Returns the organization's detailed billing information for the specified
month, broken down by daily usage per project, cluster, and service path.
Includes credits applied, discounts, running totals, and total costs.
tags:
- Billing
parameters:
- $ref: '#/components/parameters/billedMonth'
responses:
'200':
description: Detailed monthly bill retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BillsDetails'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/billsCostExplorer:
post:
operationId: queryCostExplorer
summary: Query cost explorer
description: >-
Returns usage cost details based on a custom cost explorer query.
Supports filtering and grouping by project, cluster, service, region,
and date range. Use this endpoint to build custom billing dashboards
and spending trend reports.
tags:
- Billing
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CostExplorerRequest'
responses:
'200':
description: Cost explorer results retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BillsCostExplorer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
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.
parameters:
clusterId:
name: clusterId
in: path
description: The unique identifier of the TiDB Cloud Dedicated cluster.
required: true
schema:
type: string
regionId:
name: regionId
in: path
description: The unique identifier of the cloud region.
required: true
schema:
type: string
importId:
name: importId
in: path
description: The unique identifier of the import task.
required: true
schema:
type: string
accessKey:
name: accessKey
in: path
description: The public access key portion of the API key pair.
required: true
schema:
type: string
billedMonth:
name: billedMonth
in: path
description: The billing month in YYYY-MM format (e.g., 2025-03).
required: true
schema:
type: string
pattern: '^\d{4}-\d{2}$'
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'
schemas:
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'
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'
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.
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.
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'
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
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tidb/refs/heads/main/openapi/tidb-cloud-api-openapi.yml