Every API here is available over the APIs.io API and to AI agents over MCP.
{
"swagger": "2.0",
"info": {
"title": "TiDB Cloud Starter and Essential API",
"description": "*TiDB Cloud API is in beta.*\n\nThis API manages [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-serverless) and [TiDB Cloud Essential](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#essential) instances. For [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) clusters, use the [TiDB Cloud Dedicated API](https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated/). For more information about TiDB Cloud API, see [TiDB Cloud API Overview](https://docs.pingcap.com/tidbcloud/api-overview/).\n\n# Overview\n\nThe TiDB Cloud Starter and Essential API is a [REST interface](https://en.wikipedia.org/wiki/Representational_state_transfer) that provides you with programmatic access to manage TiDB Cloud Starter and Essential instances and related resources within TiDB Cloud.\n\nThe API has the following features:\n\n- **JSON entities.** All entities are expressed in JSON.\n- **HTTPS-only.** You can only access the API via HTTPS, ensuring all the data sent over the network is encrypted with TLS.\n- **Key-based access and digest authentication.** Before you access TiDB Cloud API, you must generate an API key. All requests are authenticated through [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication), ensuring the API key is never sent over the network.\n\n# Get Started\n\nThis guide helps you make your first API call to TiDB Cloud API. You'll learn how to authenticate a request, build a request, and interpret the response.\n\n## Prerequisites\n\nTo complete this guide, you need to perform the following tasks:\n\n- Create a [TiDB Cloud account](https://tidbcloud.com/free-trial)\n- Install [curl](https://curl.se/)\n\n## Step 1. Create an API key\n\nTo create an API key, log in to your TiDB Cloud console. Navigate to the [**API Keys**](https://tidbcloud.com/org-settings/api-keys) page of your organization, and create an API key.\n\nAn API key contains a public key and a private key. Copy and save them in a secure location. You will need to use the API key later in this guide.\n\nFor more details about creating API keys, refer to [API Key Management](#section/Authentication/API-Key-Management).\n\n## Step 2. Make your first API call\n\n### Build an API call\n\nTiDB Cloud API call consists of the following components:\n\n- **A host**. The host for TiDB Cloud API is \u003chttps://serverless.tidbapi.com\u003e.\n- **An API Key**. The public key and the private key are required for authentication.\n- **A request**. When submitting data to a resource via `POST`, `PATCH`, or `PUT`, you must submit your payload in JSON.\n\nIn this guide, you call the [List all clusters](#tag/Cluster/operation/ClusterService_ListClusters) endpoint. For the detailed description of the endpoint, see the [API reference](#tag/Cluster/operation/ClusterService_ListClusters).\n\n### Call an API endpoint\n\nTo get all TiDB Cloud Starter and Essential instances in your organization, run the following command in your terminal. Remember to change `YOUR_PUBLIC_KEY` to your public key and `YOUR_PRIVATE_KEY` to your private key.\n\n```shell\ncurl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://serverless.tidbapi.com/v1beta1/clusters'\n```\n\n## Step 3. Check the response\n\nAfter making the API call, if the status code in response is `200` and you see details about all TiDB Cloud Starter and Essential instances in your organization, your request is successful.\n\n# Authentication\n\nThe TiDB Cloud API uses [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication). It protects your private key from being sent over the network. For more details about HTTP Digest Authentication, refer to the [IETF RFC](https://datatracker.ietf.org/doc/html/rfc7616).\n\n## API key overview\n\n- 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.\n- The API key belongs to your organization and acts as the `Organization Owner` role. You can check [permissions of owner](https://docs.pingcap.com/tidbcloud/manage-user-access#configure-member-roles).\n- You must provide the correct API key in every request. Otherwise, TiDB Cloud responds with a `401` error.\n\n## API key management\n\n### Create an API key\n\nOnly the **owner** of an organization can create an API key.\n\nTo create an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **Create API Key**.\n4. Enter a description for your API key.\n5. Configure the role and scope for the API key. For more information about the permissions of a role, see [User roles](https://docs.pingcap.com/tidbcloud/manage-user-access/#user-roles).\n6. Click **Generate API Key**. Copy and save the public key and the private key.\n7. 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.\n8. Click **Done**.\n\n### View details of an API key\n\nTo view details of an API key, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. You can view the details of the API keys on the page.\n\n### Edit an API key\n\nOnly the **owner** of an organization can modify an API key.\n\nTo edit an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to change, and then click **Update Role**.\n4. You can update the description and role of the API key.\n5. Click **Update**.\n\n### Delete an API key\n\nOnly the **owner** of an organization can delete an API key.\n\nTo delete an API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to delete, and then click **Delete**.\n4. Click **I understand, delete it.**\n\n# Rate Limiting\n\nThe TiDB Cloud API allows up to 100 requests per minute per API key. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519) to contact our support team.\n\nEach API request returns the following headers about the limit.\n\n- `X-Ratelimit-Limit-Minute`: The number of requests allowed per minute. It is 100 currently.\n- `X-Ratelimit-Remaining-Minute`: The number of remaining requests in the current minute. When it reaches `0`, the API returns a `429` error and indicates that you exceed the rate limit.\n- `X-Ratelimit-Reset`: The time in seconds at which the current rate limit resets.\n\nIf you exceed the rate limit, an error response returns like this.\n\n```\n\u003e HTTP/2 429\n\u003e date: Fri, 22 Jul 2022 05:28:37 GMT\n\u003e content-type: application/json\n\u003e content-length: 66\n\u003e x-ratelimit-reset: 23\n\u003e x-ratelimit-remaining-minute: 0\n\u003e x-ratelimit-limit-minute: 100\n\u003e x-kong-response-latency: 2\n\u003e server: kong/2.8.1\n\n\u003e {\"details\":[],\"code\":49900007,\"message\":\"The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519\"}\n```\n\n# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud API.\n\n\u003c!-- In reverse chronological order --\u003e\n\n## 20260414\n\n- Rename TiDB Cloud Starter and Essential clusters to TiDB Cloud Starter and Essential instances. This is only a terminology change in the API descriptions, which does not affect your API usage.\n\n## 20250812\n\n- Initial release of the TiDB Cloud Starter and Essential API, including the following resources and endpoints:\n\n - Cluster:\n - [List TiDB Cloud Starter and Essential instances](#tag/Cluster/operation/ClusterService_ListClusters)\n - [Create a new TiDB Cloud Starter or Essential instance](#tag/Cluster/operation/ClusterService_CreateCluster)\n - [Get details of a TiDB Cloud Starter or Essential instance](#tag/Cluster/operation/ClusterService_GetCluster)\n - [Delete a TiDB Cloud Starter or Essential instance](#tag/Cluster/operation/ClusterService_DeleteCluster)\n - [Update a TiDB Cloud Starter or Essential instance](#tag/Cluster/operation/ClusterService_PartialUpdateCluster)\n - [List available regions for an organization](#tag/Cluster/operation/ClusterService_ListRegions)\n - Branch:\n - [List branches](#tag/Branch/operation/BranchService_ListBranches)\n - [Create a branch](#tag/Branch/operation/BranchService_CreateBranch)\n - [Get details of a branch](#tag/Branch/operation/BranchService_GetBranch)\n - [Delete a branch](#tag/Branch/operation/BranchService_DeleteBranch)\n - [Reset a branch](#tag/Branch/operation/BranchService_ResetBranch)\n - Export:\n - [List export tasks for a cluster](#tag/Export/operation/ExportService_ListExports)\n - [Create an export task](#tag/Export/operation/ExportService_CreateExport)\n - [Get details of an export task](#tag/Export/operation/ExportService_GetExport)\n - [Delete an export task](#tag/Export/operation/ExportService_DeleteExport)\n - [Cancel an export task](#tag/Export/operation/ExportService_CancelExport)\n - Import:\n - [List import tasks for a cluster](#tag/Import/operation/ImportService_ListImports)\n - [Create an import task](#tag/Import/operation/ImportService_CreateImport)\n - [Get an import task](#tag/Import/operation/ImportService_GetImport)\n - [Cancel an import task](#tag/Import/operation/ImportService_CancelImport)\n",
"version": "v1beta1"
},
"tags": [
{
"name": "Cluster"
},
{
"name": "Branch"
},
{
"name": "Export"
},
{
"name": "Import"
}
],
"host": "serverless.tidbapi.com",
"basePath": "/v1beta1",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/clusters": {
"get": {
"summary": "List TiDB Cloud Starter and Essential instances",
"operationId": "ClusterService_ListClusters",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1ListClustersResponse"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "pageSize",
"description": "The maximum number of TiDB Cloud Starter and Essential instances to return. If not specified, at most 10 instances will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.",
"in": "query",
"required": false,
"type": "integer",
"format": "int32",
"default": 10,
"maximum": 100,
"minimum": 1
},
{
"name": "pageToken",
"description": "The pagination token received from a previous [List clusters](#tag/Cluster/operation/ClusterService_ListClusters) request. Use this token to retrieve the next page of results.\n\n**Note**: When paginating, all other parameters must match the original request.",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "filter",
"description": "An expression that filters the list of TiDB Cloud Starter and Essential instances based on specific criteria. Uses Google AIP syntax with `=` and `AND` operators. You can filter by `region`, `state`, `projectId`, `clusterId`, `displayName`, and `labels`.\n\n**Available filters**:\n- `region.provider`: the cloud provider where the TiDB Cloud Starter or Essential instance is located, such as `aws` or `alicloud`.\n- `region.name`: the name of the region where the TiDB Cloud Starter or Essential instance is located, in the format of `regions/{provider}-{region}`, such as `regions/aws-us-east-1`.\n- `state`: the state of the TiDB Cloud Starter or Essential instance, such as `ACTIVE` or `CREATING`.\n- `projectId`: the ID of the project ID. You can specify multiple values separated by commas.\n- `clusterId`: the ID of the TiDB Cloud Starter or Essential instance. You can specify multiple values separated by commas.\n- `displayName`: the display name of the TiDB Cloud Starter or Essential instance.\n- `labels.{key}`: the labels of the TiDB Cloud Starter or Essential instance, such as `labels.environment=production`.\n\n**Examples**:\n- `filter=region.provider=\"aws\" AND state=\"ACTIVE\"`\n- `filter=projectId=12345 AND displayName=\"my-cluster\"`",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "skip",
"description": "The number of TiDB Cloud Starter and Essential instances to skip before returning results. If the value exceeds the total number of these instances, the response is `200` with an empty list and no `nextPageToken`.",
"in": "query",
"required": false,
"type": "integer",
"format": "int32"
}
],
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
}
]
},
"post": {
"summary": "Create a new TiDB Cloud Starter or Essential instance",
"description": "**Note**: To create a TiDB Cloud Essential instance, you must specify valid `autoScaling.minRcu` and `autoScaling.maxRcu` values. Otherwise, a TiDB Cloud Starter instance is created by default.",
"operationId": "ClusterService_CreateCluster",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "cluster",
"description": "The TiDB Cloud Starter or Essential instance to create.",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
}
}
],
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"displayName\": \"test\",\n \"labels\": {\n \"tidb.cloud/project\": \"2293484\"\n },\n \"region\": {\n \"name\": \"regions/aws-us-east-1\"\n }\n}'"
}
]
}
},
"/clusters/{clusterId}": {
"get": {
"summary": "Get details of a TiDB Cloud Starter or Essential instance",
"operationId": "ClusterService_GetCluster",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "clusterId",
"description": "The ID of the TiDB Cloud Starter or Essential instance to retrieve.",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "view",
"description": "The detail level of the instance information to return.\n\n- `BASIC`: returns only basic instance information.\n- `FULL`: returns complete instance details.",
"in": "query",
"required": false,
"type": "string",
"default": "FULL",
"enum": [
"BASIC",
"FULL"
]
}
],
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
}
]
},
"delete": {
"summary": "Delete a TiDB Cloud Starter or Essential instance",
"operationId": "ClusterService_DeleteCluster",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "clusterId",
"description": "The ID of the TiDB Cloud Starter or Essential instance to delete.",
"in": "path",
"required": true,
"type": "string"
}
],
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location --request DELETE 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
}
]
}
},
"/clusters/{cluster.clusterId}": {
"patch": {
"summary": "Update a TiDB Cloud Starter or Essential instance",
"operationId": "ClusterService_PartialUpdateCluster",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1Cluster"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "cluster.clusterId",
"description": "The ID of the TiDB Cloud Starter or Essential instance to update.",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/v1beta1ClusterServicePartialUpdateClusterBody"
}
}
],
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location --request PATCH 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"updateMask\": \"displayName\",\n \"cluster\": {\n \"displayName\": \"test\",\n \"spendingLimit\": {\n \"monthly\": 10000\n },\n \"automatedBackupPolicy\": {\n \"startTime\": \"10:00\"\n },\n \"endpoints\": {\n \"public\": {\n \"disabled\": false,\n \"authorizedNetworks\": [\n {\n \"startIpAddress\": \"0.0.0.0\",\n \"endIpAddress\": \"255.255.255.255\",\n \"displayName\": \"allow-all\"\n }\n ]\n }\n },\n \"labels\": {\n \"label1\": \"label1\"\n },\n \"auditLogConfig\": {\n \"enabled\": true,\n \"unredacted\": true\n },\n \"autoScaling\": {\n \"minRcu\": 20000,\n \"maxRcu\": 30000\n }\n }\n}'"
}
]
}
},
"/regions": {
"get": {
"summary": "List available regions for an organization",
"description": "Before creating a TiDB Cloud Starter or Essential instance, you can use this endpoint to list available regions in your organization.",
"operationId": "ClusterService_ListRegions",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/tidb_cloud_open_apiserverlessv1beta1ListRegionsResponse"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"tags": [
"Cluster"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location 'https://serverless.tidbapi.com/v1beta1/regions' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
}
]
}
},
"/clusters/{clusterId}/branches": {
"get": {
"summary": "List branches",
"operationId": "BranchService_ListBranches",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/v1beta1ListBranchesResponse"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"429": {
"description": "You have exceed the rate limit.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"500": {
"description": "Internal server error.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"default": {
"description": "An unexpected error response.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
}
},
"parameters": [
{
"name": "clusterId",
"description": "The ID of the TiDB Cloud Starter or Essential instance to which the [branch](https://docs.pingcap.com/tidbcloud/branch-overview/) belongs.",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "pageSize",
"description": "The maximum number of branches to return. If not specified, at most 10 branches will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.",
"in": "query",
"required": false,
"type": "integer",
"format": "int32",
"default": 10,
"maximum": 100,
"minimum": 1
},
{
"name": "pageToken",
"description": "The pagination token received from a previous [List branches](#tag/Branch/operation/BranchService_ListBranches) request. Use this token to retrieve the next page of results.\n\n**Note**: When paginating, all other parameters must match the original request.",
"in": "query",
"required": false,
"type": "string"
}
],
"tags": [
"Branch"
],
"x-codeSamples": [
{
"label": "curl",
"lang": "cURL",
"source": "curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/branches' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'"
}
]
},
"post": {
"summary": "Create a branch",
"operationId": "BranchService_CreateBranch",
"responses": {
"200": {
"description": "A successful response.",
"schema": {
"$ref": "#/definitions/v1beta1Branch"
}
},
"400": {
"description": "A request field is invalid.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"401": {
"description": "The API key cannot be authenticated.",
"schema": {
"$ref": "#/definitions/googlerpcStatus"
}
},
"403": {
"description": "The API key does not have permission to access the resource.",
"schema": {
"$ref": "#/definitions/googlerpcSt
# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tidb/refs/heads/main/openapi/_original/tidb-cloud-starter-essential-v1beta1-openapi-original.json