API docs by Redocly

TiDB Cloud Premium API (v1beta2)

Download OpenAPI specification:Download

TiDB Cloud API is in beta.

This API manages TiDB Cloud Premium instances. For more information about TiDB Cloud API, see TiDB Cloud API Overview.

Overview

The TiDB Cloud Premium API (v1beta2) provides REST endpoints to manage TiDB Cloud Premium instances and related resources.

You can use this API to manage the following resources:

  • TiDB Cloud Premium instance: manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information.
  • Backup: manage backups for TiDB Cloud Premium instances, including backup-based restore.
  • Region: retrieve available regions for deploying TiDB Cloud Premium instances.

Get Started

This guide helps you make your first API call to the TiDB Cloud Premium API. You will learn how to authenticate a request, build a request, and interpret the response.

  1. Create a TiDB Cloud account if you do not already have one.

  2. In the TiDB Cloud console, go to Organization > API Keys and create an API key. For more information, see API key management.

  3. Make your first API call.

    To get all TiDB Cloud Premium instances in your organization, run the following command in your terminal. Replace YOUR_PUBLIC_KEY and YOUR_PRIVATE_KEY with your own key values.

    curl --digest \
  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
  --request GET \
  --url 'https://cloud.tidbapi.com/v1beta2/tidbs' \
  --header 'Accept: application/json'

  4. The API returns a JSON list of your TiDB Cloud Premium instances. If none exist, the response contains an empty list.

Authentication

The TiDB Cloud API uses HTTP Digest Authentication. It protects your private key from being sent over the network. For more details about HTTP Digest Authentication, refer to the IETF RFC.

API key overview

  • The API key contains a public key and a private key, which act as the username and password required in the HTTP Digest Authentication. The private key only displays upon the key creation.
  • The API key belongs to your organization and acts as the Organization Owner role. You can check permissions of owner.
  • You must provide the correct API key in every request. Otherwise, TiDB Cloud responds with a 401 error.

API key management

Create an API key

Only the owner of an organization can create an API key.

To create an API key in an organization, perform the following steps:

  1. In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
  2. In the left navigation pane, click Organization Settings > API Keys.
  3. On the API Keys page, click Create API Key.
  4. Enter a description for your API key. The role of the API key is always Organization Owner currently.
  5. Click Next. Copy and save the public key and the private key.
  6. Make sure that you have copied and saved the private key in a secure location. The private key only displays upon the creation. After leaving this page, you will not be able to get the full private key again.
  7. Click Done.

View details of an API key

To view details of an API key, perform the following steps:

  1. In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
  2. In the left navigation pane, click Organization Settings > API Keys.
  3. You can view the details of the API keys on the page.

Edit an API key

Only the owner of an organization can modify an API key.

To edit an API key in an organization, perform the following steps:

  1. In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
  2. In the left navigation pane, click Organization Settings > API Keys.
  3. On the API Keys page, click ... in the API key row that you want to change, and then click Edit.
  4. You can update the API key description.
  5. Click Update.

Delete an API key

Only the owner of an organization can delete an API key.

To delete an API key in an organization, perform the following steps:

  1. In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
  2. In the left navigation pane, click Organization Settings > API Keys.
  3. On the API Keys page, click ... in the API key row that you want to delete, and then click Delete.
  4. Click I understand, delete it.

API Changelog

This changelog lists all changes to the TiDB Cloud Premium API (v1beta2).

TiDB Cloud Premium Instance

Manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information.

List TiDB Cloud Premium instances

Lists all TiDB Cloud Premium instances in your organization. You can filter results by service plan, region, name, or ID.

query Parameters
servicePlan
string
Enum: "Starter" "Essential" "Premium" "BYOC" "Dedicated"

The plan of the service. If specified, only TiDB Cloud Premium instances of the specified plan are returned.

regionIds
Array of strings

A list of region IDs. If specified, only TiDB Cloud Premium instances in these regions are returned.

name
string

The display name to filter by. If specified, only TiDB Cloud Premium instances whose display name contains this value are returned.

tidbIds
Array of strings

A list of TiDB Cloud Premium instance IDs. If specified, only the ones matching these IDs are returned.

pageSize
integer <int32>
Default: "10"

The maximum number of TiDB Cloud Premium instances to return. If not specified, at most 10 will be returned. The maximum value is 100. Values greater than 100 are set to 100.

pageToken
string

The pagination token received from a previous List TiDB Cloud Premium instances request. Use this token to retrieve the next page of results.

Note: When paginating, all other parameters must match the original request.

skip
integer <int32>

The number of TiDB Cloud Premium instances to skip before returning results. If the value exceeds the total number of TiDB Cloud Premium instances, the response is 200 with an empty list and no nextPageToken.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "tidbs": [
    ],
  • "totalSize": 0,
  • "nextPageToken": "string"
}

Create a TiDB Cloud Premium instance

Creates a new TiDB Cloud Premium instance. If the tidb.cloud/project label is provided, the instance will be created in the specified project.

query Parameters
validateOnly
boolean

If set to true, the request is validated but not executed. Defaults to false.

Request Body schema: application/json

The TiDB Cloud Premium instance to create.

displayName
required
string [ 4 .. 64 ] characters ^[A-Za-z0-9][-A-Za-z0-9]{2,62}[A-Za-z0-9]$

The user-defined name of the TiDB Cloud Premium instance.

regionId
required
string

The unique identifier of the region where the TiDB Cloud Premium instance is deployed, in the format of {cloud_provider}-{region_code}. For example, aws-us-west-2.

rootPassword
string [ 8 .. 64 ] characters ^.{8,64}$

The root password of the TiDB Cloud Premium instance. It must be between 8 and 64 characters long and can contain letters, numbers, and special characters.

maxRcu
required
string <int64>

The maximum number of Request Capacity Units (RCUs) for the TiDB Cloud Premium instance.

servicePlan
required
string
Enum: "Starter" "Essential" "Premium" "BYOC" "Dedicated"

The plan of the service.

object

The annotations for the TiDB Cloud Premium instance. The following lists some predefined annotations:

  • tidb.cloud/has-set-password: indicates whether the TiDB Cloud Premium instance has a root password set.
  • tidb.cloud/available-features: lists available features of the TiDB Cloud Premium instance.
object

The labels for the TiDB Cloud Premium instance.

  • tidb.cloud/organization: the ID of the organization where the TiDB Cloud Premium instance belongs.
  • tidb.cloud/project: the ID of the project where the TiDB Cloud Premium instance belongs.
object

The dual-layer data encryption configuration for the TiDB Cloud Premium instance.

Responses

Request samples

Content type
application/json
{
  • "displayName": "foo-bar",
  • "regionId": "string",
  • "rootPassword": "my-shining-password",
  • "maxRcu": "string",
  • "servicePlan": "Starter",
  • "annotations": {
    },
  • "labels": {
    },
  • "dualLayerDataEncryption": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "tidbId": "string",
  • "displayName": "foo-bar",
  • "regionId": "string",
  • "cloudProvider": "aws",
  • "regionDisplayName": "string",
  • "state": "CREATING",
  • "rootPassword": "my-shining-password",
  • "minRcu": "string",
  • "maxRcu": "string",
  • "servicePlan": "Starter",
  • "highAvailabilityType": "REGIONAL",
  • "annotations": {
    },
  • "labels": {
    },
  • "creator": "string",
  • "createTime": "2019-08-24T14:15:22Z",
  • "updateTime": "2019-08-24T14:15:22Z",
  • "endpoints": [
    ],
  • "dualLayerDataEncryption": {
    },
  • "tidbVersion": "string"
}

Get a TiDB Cloud Premium instance

Retrieves details of a specific TiDB Cloud Premium instance.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance to retrieve.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "name": "string",
  • "tidbId": "string",
  • "displayName": "foo-bar",
  • "regionId": "string",
  • "cloudProvider": "aws",
  • "regionDisplayName": "string",
  • "state": "CREATING",
  • "rootPassword": "my-shining-password",
  • "minRcu": "string",
  • "maxRcu": "string",
  • "servicePlan": "Starter",
  • "highAvailabilityType": "REGIONAL",
  • "annotations": {
    },
  • "labels": {
    },
  • "creator": "string",
  • "createTime": "2019-08-24T14:15:22Z",
  • "updateTime": "2019-08-24T14:15:22Z",
  • "endpoints": [
    ],
  • "dualLayerDataEncryption": {
    },
  • "tidbVersion": "string"
}

Delete a TiDB Cloud Premium instance

Deletes a TiDB Cloud Premium instance by tidbId.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance to delete.

query Parameters
validateOnly
boolean

If set to true, the request is validated but not executed. Defaults to false.

Responses

Request samples 

curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "name": "string",
  • "tidbId": "string",
  • "displayName": "foo-bar",
  • "regionId": "string",
  • "cloudProvider": "aws",
  • "regionDisplayName": "string",
  • "state": "CREATING",
  • "rootPassword": "my-shining-password",
  • "minRcu": "string",
  • "maxRcu": "string",
  • "servicePlan": "Starter",
  • "highAvailabilityType": "REGIONAL",
  • "annotations": {
    },
  • "labels": {
    },
  • "creator": "string",
  • "createTime": "2019-08-24T14:15:22Z",
  • "updateTime": "2019-08-24T14:15:22Z",
  • "endpoints": [
    ],
  • "dualLayerDataEncryption": {
    },
  • "tidbVersion": "string"
}

Update a TiDB Cloud Premium instance

Updates the configuration of a specific TiDB Cloud Premium instance. You can modify the following fields: displayName and maxRcu.

path Parameters
tidb.tidbId
required
string

The ID of the TiDB Cloud Premium instance to update.

query Parameters
validateOnly
boolean

If set to true, the request is validated but not executed. Defaults to false.

Request Body schema: application/json

The TiDB Cloud Premium instance to update.

displayName
string [ 4 .. 64 ] characters ^[A-Za-z0-9][-A-Za-z0-9]{2,62}[A-Za-z0-9]$

The user-defined name of the cluster.

maxRcu
string <int64>

The maximum number of Request Capacity Units (RCUs) for the TiDB Cloud Premium instance.

Responses

Request samples

Content type
application/json
{
  • "displayName": "foo-bar",
  • "maxRcu": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "tidbId": "string",
  • "displayName": "foo-bar",
  • "regionId": "string",
  • "cloudProvider": "aws",
  • "regionDisplayName": "string",
  • "state": "CREATING",
  • "rootPassword": "my-shining-password",
  • "minRcu": "string",
  • "maxRcu": "string",
  • "servicePlan": "Starter",
  • "highAvailabilityType": "REGIONAL",
  • "annotations": {
    },
  • "labels": {
    },
  • "creator": "string",
  • "createTime": "2019-08-24T14:15:22Z",
  • "updateTime": "2019-08-24T14:15:22Z",
  • "endpoints": [
    ],
  • "dualLayerDataEncryption": {
    },
  • "tidbVersion": "string"
}

Reset the root password of a TiDB Cloud Premium instance

Sets a new password for the TiDB Cloud Premium instance's root user. The new password is not returned in the response for security reasons, so save your password in a secure location.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance for which to reset the root password.

Request Body schema: application/json
rootPassword
required
string [ 8 .. 64 ] characters ^.{8,64}$

The new root password. It must be between 8 and 64 characters long.

Responses

Request samples

Content type
application/json
{
  • "rootPassword": "my-shining-password"
}

Response samples

Content type
application/json
{ }

Get cloud provider information for a TiDB Cloud Premium instance

Retrieves the TiDB Cloud account ID and external ID for the underlying cloud infrastructure of a specific TiDB Cloud Premium instance.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance for which to retrieve cloud provider information.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/cloudProviderInfo' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "tidbId": "string",
  • "cloudProvider": "aws",
  • "tidbCloudAccountId": "string",
  • "tidbCloudAccountExternalId": "string"
}

Get the CA certificate download URL for a TiDB Cloud Premium instance

Retrieves the download URL for the CA certificate required to establish TLS (Transport Layer Security) connections to a specific TiDB Cloud Premium instance.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance for which to retrieve the CA certificate.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/caCertificateUrl' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "uri": "string"
}

Backup

Manage backups for TiDB Cloud Premium instances, including backup-based restore.

List backups for a TiDB Cloud Premium instance

Lists all backups for a specific TiDB Cloud Premium instance. You can filter results by state, region, trigger type, or time range.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance for which to list backups.

query Parameters
states
Array of strings
Items Enum: "UNKNOWN" "PENDING" "RUNNING" "SUCCEEDED" "FAILED" "CANCELLED"

A list of backup states. If specified, only backups matching these states are returned.

  • UNKNOWN: The backup state is unknown.
  • PENDING: The backup is pending.
  • RUNNING: The backup is in progress.
  • SUCCEEDED: The backup completed successfully.
  • FAILED: The backup has failed.
  • CANCELLED: The backup is cancelled.
regionIds
Array of strings

A list of region IDs. If specified, only backups in these regions are returned.

triggerTypes
Array of strings
Items Enum: "AUTO" "MANUAL"

A list of backup trigger types. If specified, only backups matching these trigger types are returned.

  • AUTO: The backup is triggered automatically by TiDB Cloud.
  • MANUAL: The backup is triggered manually by a user.
startTime
string <date-time>

The inclusive start of the backup time range, in the ISO 8601 format. If specified, only backups at or after this time are returned.

endTime
string <date-time>

The inclusive end of the backup time range, in the ISO 8601 format. If specified, only backups at or before this time are returned.

pageSize
integer <int32>
Default: "10"

The maximum number of backups to return. If not specified, at most 10 backups will be returned. The maximum value is 100. Values greater than 100 are set to 100.

pageToken
string

The pagination token received from a previous List backups for a TiDB Cloud Premium instance request. Use this token to retrieve the next page of results.

Note: When paginating, all other parameters must match the original request.

skip
integer <int32>

The number of backups to skip before returning results. If the value exceeds the total number of backups, the response is 200 with an empty list and no nextPageToken.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/backups' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "backups": [
    ],
  • "totalSize": 0,
  • "nextPageToken": "string"
}

Delete a backup for a TiDB Cloud Premium instance

Deletes a backup by backupId.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance.

backupId
required
string

The ID of the backup to delete.

Responses

Request samples 

curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/backups/{backup_id}' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{ }

Restore a TiDB Cloud Premium instance from a backup

Restores a new TiDB Cloud Premium instance from a backup. Supported restore modes: SNAPSHOT, PITR, DEDICATED_SNAPSHOT, and CLASSIC_SNAPSHOT.

Request Body schema: application/json
required
object

The configuration of the TiDB Cloud Premium instance to create.

Note: Currently, only TiDB Cloud Premium instances with servicePlan set to Premium are supported.

sourceTidbId
string

The ID of the source TiDB Cloud Premium instance containing the backup data.

restoreMode
required
string (v1beta2RestoreMode)
Enum: "SNAPSHOT" "PITR" "DEDICATED_SNAPSHOT" "CLASSIC_SNAPSHOT"

The mode used to restore a TiDB Cloud Premium instance.

  • SNAPSHOT: Restores from native snapshot backup data of a TiDB Cloud Premium instance.
  • PITR: Restores from native point-in-time recovery (PITR) backup data of a TiDB Cloud Premium instance.
  • DEDICATED_SNAPSHOT: Restores from snapshot backup data of a TiDB Cloud Dedicated cluster.
  • CLASSIC_SNAPSHOT: Restores from snapshot backup data stored in object storage of a classic TiDB
backupId
string

The ID of the backup to restore from.

This field is required when restoreMode is "SNAPSHOT" or "DEDICATED_SNAPSHOT".

pointInTime
string <date-time>

The point in time to restore data to, in the ISO 8601 format.

This field is required when restoreMode is "PITR".

object

The classic backup storage configuration.

This field is required when restoreMode is "CLASSIC_SNAPSHOT".

validateOnly
boolean

If set to true, the request is validated but not executed. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "tidb": {
    },
  • "sourceTidbId": "string",
  • "restoreMode": "SNAPSHOT",
  • "backupId": "string",
  • "pointInTime": "2019-08-24T14:15:22Z",
  • "classicBackupStorage": {
    },
  • "validateOnly": true
}

Response samples

Content type
application/json
{
  • "tidb": {
    }
}

Get the restore state for a TiDB Cloud Premium instance

Retrieves the restore progress of a TiDB Cloud Premium instance, including the completion percentage and any error messages.

path Parameters
tidbId
required
string

The ID of the TiDB Cloud Premium instance.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}:getRestoreStatus' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "state": "UNKNOWN",
  • "message": "string",
  • "progress": 0
}

Region

Retrieve available regions for deploying TiDB Cloud Premium instances.

List regions

Lists the regions where you can create a TiDB Cloud Premium instance. You can filter results by cloud provider or service plan.

query Parameters
cloudProvider
string

The cloud provider. If specified, only regions belonging to the specified cloud provider are returned.

servicePlan
string
Enum: "Starter" "Essential" "Premium" "BYOC" "Dedicated"

The plan of the service. If specified, only regions that support the specified service plan are returned.

pageSize
integer <int32>
Default: "10"

The maximum number of regions to return. If not specified, at most 10 regions will be returned. The maximum value is 100. Values greater than 100 are set to 100.

pageToken
string

The pagination token received from a previous List regions request. Use this token to retrieve the next page of results.

Note: When paginating, all other parameters must match the original request.

skip
integer <int32>

The number of regions to skip before returning results. If the value exceeds the total number of regions, the response is 200 with an empty list and no nextPageToken.

Responses

Request samples 

curl --location 'https://cloud.tidbapi.com/v1beta2/regions' \
--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "regions": [
    ],
  • "totalSize": 0,
  • "nextPageToken": "string"
}