TiDB Cloud Starter and Essential API (v1beta1)

{
  "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/pingcap/refs/heads/main/openapi/pingcap-tidb-cloud-starter-essential-v1beta1-openapi-original.json