{ "swagger": "2.0", "info": { "title": "TiDB Cloud Dedicated API", "description": "*TiDB Cloud API is in beta.*\n\nThis API manages [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) clusters. For TiDB Cloud Starter or TiDB Cloud Essential instances, use the [TiDB Cloud Starter and Essential API](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless). 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 API is a [REST interface](https://en.wikipedia.org/wiki/Representational_state_transfer) that provides you with programmatic access to manage clusters 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 .\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 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 clusters 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://dedicated.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 clusters 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> HTTP/2 429\n> date: Fri, 22 Jul 2022 05:28:37 GMT\n> content-type: application/json\n> content-length: 66\n> x-ratelimit-reset: 23\n> x-ratelimit-remaining-minute: 0\n> x-ratelimit-limit-minute: 100\n> x-kong-response-latency: 2\n> server: kong/2.8.1\n\n> {\"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\n\n## 20260707\n\n- Introduce the following Changefeed endpoints for managing changefeeds:\n\t* [List changefeed RCU options](#tag/Changefeed/operation/ListChangefeedRCUs)\n\t* [List changefeeds](#tag/Changefeed/operation/ListChangefeeds)\n\t* [Create a changefeed](#tag/Changefeed/operation/CreateChangefeed)\n\t* [Get a changefeed](#tag/Changefeed/operation/GetChangefeed)\n\t* [Delete a changefeed](#tag/Changefeed/operation/DeleteChangefeed)\n\t* [Update a changefeed downstream config](#tag/Changefeed/operation/EditChangefeedDownstreamConfig)\n\t* [Pause a changefeed](#tag/Changefeed/operation/PauseChangefeed)\n\t* [Resume a changefeed](#tag/Changefeed/operation/ResumeChangefeed)\n\t* [Scale a changefeed](#tag/Changefeed/operation/ScaleChangefeed)\n\n## 20251028\n\n- Introduce the following TiDB Cloud Dedicated API endpoints for managing third-party monitoring integrations:\n\t* [List integrations](#tag/Integration/operation/IntegrationService_ListIntegrations)\n\t* [Create an integration](#tag/Integration/operation/IntegrationService_CreateIntegration)\n\t* [Delete an integration](#tag/Integration/operation/IntegrationService_DeleteIntegration)\n\n## 20250812\n\n- Initial release of the TiDB Cloud Dedicated API, including the following resources and endpoints:\n\t* Cluster\n\t\t* [List clusters](#tag/Cluster/operation/ClusterService_ListClusters)\n\t\t* [Create a cluster](#tag/Cluster/operation/ClusterService_CreateCluster)\n\t\t* [Get a cluster](#tag/Cluster/operation/ClusterService_GetCluster)\n\t\t* [Delete a cluster](#tag/Cluster/operation/ClusterService_DeleteCluster)\n\t\t* [Update a cluster](#tag/Cluster/operation/ClusterService_UpdateCluster)\n\t\t* [Pause a cluster](#tag/Cluster/operation/ClusterService_PauseCluster)\n\t\t* [Resume a cluster](#tag/Cluster/operation/ClusterService_ResumeCluster)\n\t\t* [Reset the root password of a cluster](#tag/Cluster/operation/ClusterService_ResetRootPassword)\n\t\t* [List node quotas for your organization](#tag/Cluster/operation/ClusterService_ShowNodeQuota)\n\t\t* [Get log redaction policy](#tag/Cluster/operation/ClusterService_GetLogRedactionPolicy)\n\t* Region\n\t\t* [List regions](#tag/Region/operation/RegionService_ListRegions)\n\t\t* [Get a region](#tag/Region/operation/RegionService_GetRegion)\n\t\t* [List cloud providers](#tag/Region/operation/RegionService_ShowCloudProviders)\n\t\t* [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs)\n\t\t* [Get a node spec](#tag/Region/operation/RegionService_GetNodeSpec)\n\t* Private Endpoint Connection\n\t\t* [Get private link service for a TiDB node group](#tag/Private-Endpoint-Connection/operation/PrivateEndpointConnectionService_GetPrivateLinkService)\n\t\t* [Create a private endpoint connection](#tag/Private-Endpoint-Connection/operation/PrivateEndpointConnectionService_CreatePrivateEndpointConnection)\n\t\t* [List private endpoint connections](#tag/Private-Endpoint-Connection/operation/PrivateEndpointConnectionService_ListPrivateEndpointConnections)\n\t\t* [Get a private endpoint connection](#tag/Private-Endpoint-Connection/operation/PrivateEndpointConnectionService_GetPrivateEndpointConnection)\n\t\t* [Delete a private endpoint connection](#tag/Private-Endpoint-Connection/operation/PrivateEndpointConnectionService_DeletePrivateEndpointConnection)\n\t* Import\n\t\t* [List import tasks](#tag/Import/operation/ListImports)\n\t\t* [Create an import task](#tag/Import/operation/CreateImport)\n\t\t* [Get an import task](#tag/Import/operation/GetImport)\n\t\t* [Cancel an import task](#tag/Import/operation/CancelImport)\n\t\n", "version": "v1beta1" }, "tags": [ { "name": "Cluster", "description": "Create, get, update, delete, pause, resume, reset the root password, and list node quotas of a cluster." }, { "name": "Region", "description": "List regions, get a region, and list cloud providers and node specs of a region." }, { "name": "Private Endpoint Connection", "description": "Get private link service for a TiDB node group, create a private endpoint connection, list private endpoint connections, get a private endpoint connection, and delete a private endpoint connection." }, { "name": "Import", "description": "List import tasks, create an import task, get an import task, and cancel an import task." }, { "name": "Integration", "description": "List integrations, create an integration, and delete an integration." }, { "name": "Changefeed", "description": "List changefeed RCU options, list changefeeds, create a changefeed, get a changefeed, delete a changefeed, update a changefeed downstream config, pause a changefeed, resume a changefeed, and scale a changefeed." } ], "x-tagGroups": [ { "name": "Endpoints", "tags": [ "Cluster", "Region", "Private Endpoint Connection", "Import", "Integration", "Changefeed" ] } ], "host": "dedicated.tidbapi.com", "basePath": "/v1beta1", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/clusters": { "get": { "summary": "List clusters", "description": "Lists all clusters in your organization. You can filter results by project, region, cluster state, or specific cluster IDs.", "operationId": "ClusterService_ListClusters", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1ListClustersResponse" } }, "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": "projectId", "description": "The ID of the project. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" }, { "name": "clusterIds", "description": "A list of cluster IDs. If specified, only clusters matching these IDs are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "regionIds", "description": "A list of region IDs. If specified, only clusters in these regions are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "clusterStates", "description": "A list of cluster states. If specified, only clusters in these states are returned.\n\n`\"UPGRADING\"`, `\"IMPORTING\"`, `\"MODIFYING\"`, `\"PAUSING\"`, `\"PAUSED\"`, and `\"RESUMING\"` states are only available for [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) clusters.\n\n - CREATING: Cluster is being created.\n - DELETING: Cluster is being deleted.\n - ACTIVE: Cluster is active for use.\n - RESTORING: Cluster data is being restored.\n - MAINTENANCE: Cluster is under maintenance.\n - DELETED: Cluster has been deleted.\n - INACTIVE: Cluster is not active, but not being deleted.\n - UPGRADING: Cluster is being updated.\nOnly for Dedicated Cluster.\n - IMPORTING: Cluster is being imported.\nOnly for Dedicated Cluster.\n - MODIFYING: Cluster is being modified.\nOnly for Dedicated Cluster.\n - PAUSING: Cluster is being paused.\nOnly for Dedicated Cluster.\n - PAUSED: Cluster is paused.\nOnly for Dedicated Cluster.\n - RESUMING: Cluster is resuming.\nOnly for Dedicated Cluster.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "CREATING", "DELETING", "ACTIVE", "RESTORING", "MAINTENANCE", "DELETED", "INACTIVE", "UPGRADING", "IMPORTING", "MODIFYING", "PAUSING", "PAUSED", "RESUMING" ] }, "collectionFormat": "multi" }, { "name": "pageSize", "description": "The maximum number of clusters to return. If not specified, at most 10 clusters 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, "minimum": 1, "maximum": 100 }, { "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": "skip", "description": "The number of clusters to skip before returning results. If the value exceeds the total number of clusters, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters'" } ] }, "post": { "summary": "Create a cluster", "description": "Creates a new [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) cluster. Before creating a TiDB Cloud Dedicated cluster, you must set a [Project CIDR on TiDB Cloud console](https://docs.pingcap.com/tidbcloud/set-up-vpc-peering-connections/#prerequisite-set-a-cidr-for-a-region).", "operationId": "ClusterService_CreateCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } }, "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": "Required.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } }, { "name": "validateOnly", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters' --header 'Content-Type: application/json' --data '{\n \"displayName\": \"foo-bar\",\n \"regionId\": \"aws-us-west-2\",\n \"labels\": {\n \"tidb.cloud/project\": \"YOUR_PROJECT_ID\"\n },\n \"tidbNodeSetting\": {\n \"nodeSpecKey\": \"8C32G\",\n \"tidbNodeGroups\": [\n {\n \"nodeCount\": 2\n }\n ]\n },\n \"tikvNodeSetting\": {\n \"nodeCount\": 3,\n \"nodeSpecKey\": \"8C32G\",\n \"storageSizeGi\": 500,\n \"storageType\": \"Standard\"\n }\n}'" } ] } }, "/clusters/{clusterId}": { "get": { "summary": "Get a cluster", "description": "Retrieves details of a specific cluster.", "operationId": "ClusterService_GetCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } }, "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 cluster.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}'" } ] }, "delete": { "summary": "Delete a cluster", "description": "Deletes a cluster by `clusterId`.", "operationId": "ClusterService_DeleteCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } }, "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 cluster to delete.", "in": "path", "required": true, "type": "string" }, { "name": "validateOnly", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request DELETE 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}'" } ] }, "patch": { "summary": "Update a cluster", "description": "Updates the configuration of a specific cluster. You can modify the following fields: `tidbNodeSetting`, `tikvNodeSetting`, `tiflashNodeSetting` and `displayName`.", "operationId": "ClusterService_UpdateCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } }, "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 cluster to update.", "in": "path", "required": true, "type": "string" }, { "name": "cluster", "description": "The updated cluster configuration.", "in": "body", "required": true, "schema": { "type": "object", "properties": { "tidbNodeSetting": { "description": "The TiDB node setting for updating a cluster. \n\nTo get the node spec available configurations of a specific region for a cloud provider, refer to [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) API.", "allOf": [ { "$ref": "#/definitions/v1beta1UpdateClusterRequestTidbNodeSetting" } ] }, "tikvNodeSetting": { "description": "The TiKV node setting for updating a cluster. \n\nTo get the node spec available configurations of a specific region for a cloud provider, refer to [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) API.", "allOf": [ { "$ref": "#/definitions/v1beta1UpdateClusterRequestStorageNodeSetting" } ] }, "tiflashNodeSetting": { "example": { "nodeCount": 3, "nodeSpecKey": "16C128G", "storageSizeGi": 500, "storageType": "Basic" }, "description": "The TiFlash node setting for updating a cluster. \n\nTo get the node spec available configurations of a specific region for a cloud provider, refer to [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) API.", "allOf": [ { "$ref": "#/definitions/v1beta1UpdateClusterRequestStorageNodeSetting" } ] }, "displayName": { "type": "string", "example": "My Cluster", "description": "The display name of the cluster." }, "labels": { "type": "object", "example": {}, "additionalProperties": { "type": "string" }, "description": "The labels of the cluster. Each label consists of a string key and a string value. \n\n**Note**: Currently, `labels` updates are not supported." } }, "title": "The updated cluster configuration." } }, { "name": "validateOnly", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request PATCH 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}' --header 'Content-Type: application/json' --data '{\n \"displayName\": \"My Cluster Updated By API\",\n \"tikvNodeSetting\": {\n \"storageSizeGi\": 500\n }\n}'" } ] } }, "/clusters/{clusterId}:pauseCluster": { "post": { "summary": "Pause a cluster", "description": "Pauses a cluster by ID.", "operationId": "ClusterService_PauseCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1PauseClusterResponse" } }, "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 cluster to pause.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request POST 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}:pauseCluster'" } ] } }, "/clusters/{clusterId}:resumeCluster": { "post": { "summary": "Resume a cluster", "description": "Resumes a paused cluster. Only clusters in the `PAUSED` state can be resumed.", "operationId": "ClusterService_ResumeCluster", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1ResumeClusterResponse" } }, "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 cluster to resume.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request POST 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}:resumeCluster'" } ] } }, "/clusters/{clusterId}:resetRootPassword": { "post": { "summary": "Reset the root password of a cluster", "description": "Sets a new password for the cluster's root user. The new password is not returned in the response for security reasons, so save your password in a secure location.\n\nThe cluster must be in the `READY` state. If the cluster is not `READY`, wait until it is before retrying.", "operationId": "ClusterService_ResetRootPassword", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1ResetRootPasswordResponse" } }, "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 cluster for which to reset the root password.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1beta1ClusterServiceResetRootPasswordBody" } } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}:resetRootPassword' --header 'Content-Type: application/json' --data '{\n \"rootPassword\": \"your_new_password\"\n}'" } ] } }, "/clusters:showNodeQuota": { "get": { "summary": "List node quotas for your organization", "description": "Lists the node quotas for your organization, including the maximum number of nodes allowed for each component type.", "operationId": "ClusterService_ShowNodeQuota", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1ShowNodeQuotaResponse" } }, "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-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters:showNodeQuota'" } ] } }, "/clusters/{clusterId}/logRedactionPolicy": { "get": { "summary": "Get log redaction policy", "description": "Gets the log redaction policy for a cluster.", "operationId": "ClusterService_GetLogRedactionPolicy", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1LogRedactionPolicy" } }, "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 cluster for which to get the log redaction policy.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Cluster" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/logRedactionPolicy'" } ] } }, "/regions": { "get": { "summary": "List regions", "description": "Lists the regions where you can create a cluster, across all supported cloud providers.", "operationId": "RegionService_ListRegions", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1ListRegionsResponse" } }, "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": "cloudProvider", "description": "The cloud provider where the region is located. If specified, only regions of the specified cloud provider are returned.", "in": "query", "required": false, "type": "string" }, { "name": "projectId", "description": "The ID of the project to list regions for. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" }, { "name": "pageSize", "description": "The maximum number of regions to return. If not specified, at most 20 regions 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": 20, "minimum": 1, "maximum": 100 }, { "name": "pageToken", "description": "The pagination token received from a previous [List regions](#tag/Region/operation/RegionService_ListRegions) 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": "skip", "description": "The number of regions to skip before returning results. If the value exceeds the total number of clusters, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Region" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/regions'" } ] } }, "/regions/{regionId}": { "get": { "summary": "Get a region", "description": "Retrieves details of a specific region by region ID.", "operationId": "RegionService_GetRegion", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/commonv1beta1Region" } }, "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": "regionId", "description": "The ID of the region to retrieve, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`.", "in": "path", "required": true, "type": "string" }, { "name": "projectId", "description": "The ID of the project for which to retrieve the region. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Region" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/regions/aws-us-east-1'" } ] } }, "/regions:showCloudProviders": { "get": { "summary": "List cloud providers", "description": "Lists the cloud providers available for creating a cluster.", "operationId": "RegionService_ShowCloudProviders", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1ShowCloudProvidersResponse" } }, "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": "projectId", "description": "The ID of the project. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Region" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/regions:showCloudProviders'" } ] } }, "/regions/{regionId}/nodeSpecs": { "get": { "summary": "List node specs", "description": "Retrieves a paginated list of node specifications (specs) available for creating or scaling a cluster in the specified region. You can filter the results using the `componentType`, `projectId`, or `clusterId` parameter.", "operationId": "RegionService_ListNodeSpecs", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1ListNodeSpecsResponse" } }, "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": "regionId", "description": "The ID of the region, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`.", "in": "path", "required": true, "type": "string" }, { "name": "componentType", "description": "Filters the results to include only node specs for the specified component type.", "in": "query", "required": false, "type": "string", "enum": [ "TIKV", "TIDB", "TIFLASH", "PD" ] }, { "name": "projectId", "description": "Filters the results to include only node specs available to the specified project. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" }, { "name": "clusterId", "description": "Filters the results to include only node specs available to the specified cluster. If not specified, all available node specs are returned.", "in": "query", "required": false, "type": "string" }, { "name": "pageSize", "description": "The maximum number of node specs to return. If not specified, at most 10 node specs 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, "minimum": 1, "maximum": 100 }, { "name": "pageToken", "description": "The pagination token received from a previous [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) 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": "skip", "description": "The number of node specs to skip before returning results. If the value exceeds the total number of clusters, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Region" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/regions/aws-us-east-1/nodeSpecs'" } ] } }, "/regions/{regionId}/componentTypes/{componentType}/nodeSpecs/{nodeSpecKey}": { "get": { "summary": "Get a node spec", "description": "Retrieves details of a node spec used for creating or scaling a cluster.", "operationId": "RegionService_GetNodeSpec", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1NodeSpec" } }, "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": "regionId", "description": "The region ID of the node spec to retrieve, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`. If not specified, the default region ID is used.", "in": "path", "required": true, "type": "string" }, { "name": "componentType", "description": "Filters the results to include only node specs for the specified component type.", "in": "path", "required": true, "type": "string", "enum": [ "TIKV", "TIDB", "TIFLASH", "PD" ] }, { "name": "nodeSpecKey", "description": "The key of the node spec to retrieve. For example, `8C32G`.", "in": "path", "required": true, "type": "string" }, { "name": "projectId", "description": "The ID of the project for which to retrieve the node spec. If not specified, the project ID of the default project is used.", "in": "query", "required": false, "type": "string" }, { "name": "clusterId", "description": "The ID of the cluster. If specified, only node specs that are available to the specified cluster are returned. If not specified, all available node specs are returned.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Region" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/regions/aws-us-east-1/componentTypes/TIKV/nodeSpecs/8C32G'" } ] } }, "/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateLinkService": { "get": { "summary": "Get private link service for a TiDB node group", "description": "Retrieves the private link service configuration for a [TiDB node group](https://docs.pingcap.com/tidbcloud/tidb-node-group-overview/). You can use the private link service to establish private endpoint connections to your TiDB cluster.", "operationId": "PrivateEndpointConnectionService_GetPrivateLinkService", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1PrivateLinkService" } }, "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 cluster for which to get the private link service.", "in": "path", "required": true, "type": "string" }, { "name": "tidbNodeGroupId", "description": "The ID of the TiDB node group for which to get the private link service.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Private Endpoint Connection" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateLinkService'" } ] } }, "/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections": { "get": { "summary": "List private endpoint connections", "description": "Lists private endpoint connections for a cluster and TiDB node group. To list private link connections across different clusters and TiDB node groups, set cluster_id and tidb_node_group_id to \"-\". If you want to list private link connections under a project across different clusters and TiDB node groups, set both cluster_id and tidb_node_group_id to \"-\", and pass the project_id in the query parameter.", "operationId": "PrivateEndpointConnectionService_ListPrivateEndpointConnections", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1ListPrivateEndpointConnectionsResponse" } }, "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 cluster for which to list private link connections. To list private link connections across different clusters and TiDB node groups, set as `-``.", "in": "path", "required": true, "type": "string", "pattern": "[^/]+" }, { "name": "tidbNodeGroupId", "description": "To list private link connections across different clusters and TiDB node groups, set tidb_node_group_id to \"-\".", "in": "path", "required": true, "type": "string", "pattern": "[^/]+" }, { "name": "projectId", "description": "Pass this project_id only when listing under a project across different clusters and TiDB node groups.\nBoth cluster_id and tidb_node_group_id should be set to \"-\" in this case.\nIf unspecified, the project ID of the cluster is used.", "in": "query", "required": false, "type": "string" }, { "name": "cloudProvider", "description": "If specified, only private link connections of the specified cloud provider will be returned.\n\n - aws: Amazon Web Services.\n - gcp: Google Cloud Platform.\n - azure: Microsoft Azure.\n - alicloud: Alibaba Cloud", "in": "query", "required": false, "type": "string", "enum": [ "aws", "gcp", "azure", "alicloud" ] }, { "name": "pageSize", "description": "The maximum number of private link connections to return. The service may return fewer than this value.\nIf unspecified, at most 10 private link connections will be returned.\nThe maximum value is 100; values above 100 will be coerced to 100.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "pageToken", "description": "A page token, received from a previous `ListPrivateLinkConnections` call.\nProvide this to retrieve the subsequent page.", "in": "query", "required": false, "type": "string" }, { "name": "skip", "description": "The number of individual resources to skip before starting to return results.\nIf the skip value causes the cursor to move past the end of the collection,\nthe response will be 200 OK with an empty result set and no next_page_token.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Private Endpoint Connection" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections'" } ] }, "post": { "summary": "Create a private endpoint connection", "description": "Creates a private endpoint connection for a TiDB node group. For more information, see the following documents:\n\n- [Connect via Private Endpoint with AWS](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections/) \n- [Connect via Private Endpoint with Azure](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections-on-azure/) \n- [Connect via Private Endpoint with Google Cloud](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections-on-google-cloud/)", "operationId": "PrivateEndpointConnectionService_CreatePrivateEndpointConnection", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1PrivateEndpointConnection" } }, "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 cluster for which to create the private endpoint connection.", "in": "path", "required": true, "type": "string" }, { "name": "tidbNodeGroupId", "description": "The ID of the TiDB node group to which the private endpoint connection belongs.", "in": "path", "required": true, "type": "string" }, { "name": "privateEndpointConnection", "in": "body", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "tidbNodeGroups/1/privateEndpointConnections/1234567890", "description": "The name of the private endpoint connection, in the format of `tidbNodeGroups/{tidb_node_group_id}/privateEndpointConnections/{private_endpoint_connection_id}`.", "readOnly": true }, "privateEndpointConnectionId": { "type": "string", "example": "1234567890", "description": "The unique ID of the private endpoint connection.", "readOnly": true }, "clusterId": { "type": "string", "example": "1", "description": "The ID of the cluster to which the private endpoint connection belongs.", "readOnly": true }, "clusterDisplayName": { "type": "string", "example": "my-cluster", "description": "The display name of the cluster to which the private endpoint connection belongs.", "readOnly": true }, "labels": { "type": "object", "example": { "tidb.cloud/project": "1" }, "additionalProperties": { "type": "string" }, "description": "The labels of the private link connection, including the mandatory `tidb.cloud/project` label identifying the project it belongs to. Each label consists of a string key and a string value.", "readOnly": true }, "endpointId": { "type": "string", "example": "vpce-0a1b2c3d4e5f6g7h8", "description": "The endpoint ID of the private link connection.\n\n- AWS: the VPC endpoint ID for [AWS PrivateLink\n](https://aws.amazon.com/privatelink/).\n\n- Google Cloud: the endpoint ID for [Private Service Connect](https://cloud.google.com/vpc/docs/private-service-connect).\n\n- Azure: the resource ID for [Azure Private Link](https://learn.microsoft.com/en-us/azure/private-link/private-link-overview)." }, "privateIpAddress": { "type": "string", "x-nullable": true, "description": "(Azure only) The private IP address of the private endpoint in your virtual network. TiDB Cloud automatically creates a public DNS record that resolves to this IP address, enabling you to connect using the DNS name." }, "endpointState": { "example": "ACTIVE", "description": "The state of the private endpoint connection.\n\n- `\"PENDING\"`: TiDB Cloud is asynchronously accepting the endpoint connection.\n\n- `\"ACTIVE\"`: the private endpoint connection is ready to use.\n\n- `\"DELETING\"`: the private endpoint connection is being deleted.\n\n- `\"FAILED\"`: the private endpoint connection has failed.\n- `DISCOVERED`: the endpoint is created in your VPC but not registered with TiDB Cloud.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1PrivateEndpointConnectionEndpointState" } ] }, "message": { "type": "string", "example": "", "description": "The detailed message when the `endpointState` field is `\"FAILED\"`.", "readOnly": true }, "regionId": { "type": "string", "example": "aws-us-east-1", "description": "The ID of the region where the private endpoint connection is located, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`.", "readOnly": true }, "regionDisplayName": { "type": "string", "example": "N. Virginia (us-east-1)", "description": "The display name of the region where the private endpoint connection is located. For example, `N. Virginia (us-east-1)`.", "readOnly": true }, "cloudProvider": { "example": "aws", "description": "The cloud provider where the private endpoint connection is located.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1RegionCloudProvider" } ] }, "privateLinkServiceName": { "type": "string", "example": "com.amazonaws.vpce.us-east-1.vpce-svc-1234567890", "description": "The name of the private link service that the private endpoint connection is connected to.", "readOnly": true }, "privateLinkServiceState": { "example": "ACTIVE", "description": "The state of the private link service that the private endpoint connection is connected to.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1PrivateLinkServiceState" } ] }, "tidbNodeGroupDisplayName": { "type": "string", "example": "DefaultGroup", "description": "The display name of the TiDB node group that the private endpoint connection is connected to.", "readOnly": true }, "accountId": { "type": "string", "x-nullable": true, "description": "(Google Cloud only) The project name used to identify the Google Cloud project that the private service connection belongs to.", "readOnly": true }, "host": { "type": "string", "example": "privatelink-1234567890.abcdefg.clusters.tidb-cloud.com", "description": "The hostname for accessing the TiDB cluster through the private endpoint connection.", "readOnly": true }, "port": { "type": "integer", "format": "int32", "example": 4000, "description": "The port used to connect to the TiDB cluster through the private endpoint connection.", "readOnly": true } }, "required": [ "endpointId" ] } }, { "name": "validateOnly", "description": "(Azure only) If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "Private Endpoint Connection" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections' --header 'Content-Type: application/json' --data '{\n \"endpointId\": \"vpce-0a1b2c3d4e5f6g7h8\"\n}'" } ] } }, "/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections/{privateEndpointConnectionId}": { "get": { "summary": "Get a private endpoint connection", "description": "Retrieves a private endpoint connection for a TiDB node group.", "operationId": "PrivateEndpointConnectionService_GetPrivateEndpointConnection", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/dedicatedv1beta1PrivateEndpointConnection" } }, "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 cluster for which to get the private endpoint connection.", "in": "path", "required": true, "type": "string" }, { "name": "tidbNodeGroupId", "description": "The ID of the TiDB node group for which to get the private endpoint connection.", "in": "path", "required": true, "type": "string" }, { "name": "privateEndpointConnectionId", "description": "The ID of the private endpoint connection to get.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Private Endpoint Connection" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections/{privateEndpointConnectionId}'" } ] }, "delete": { "summary": "Delete a private endpoint connection", "description": "Deletes a private endpoint connection for a TiDB node group.", "operationId": "PrivateEndpointConnectionService_DeletePrivateEndpointConnection", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "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 cluster from which to delete the private endpoint connection.", "in": "path", "required": true, "type": "string" }, { "name": "tidbNodeGroupId", "description": "The ID of the TiDB node group from which to delete the private endpoint connection.", "in": "path", "required": true, "type": "string" }, { "name": "privateEndpointConnectionId", "description": "The ID of the private endpoint connection to delete.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Private Endpoint Connection" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request DELETE 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/tidbNodeGroups/{tidbNodeGroupId}/privateEndpointConnections/{privateEndpointConnectionId}'" } ] } }, "/clusters/{clusterId}/imports": { "get": { "summary": "List import tasks", "description": "Lists all import tasks for a cluster. You can use query parameters to control sorting, pagination, and the number of results returned.", "operationId": "ListImports", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1ListImportsResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster to list import tasks for.", "in": "path", "required": true, "type": "string" }, { "name": "pageToken", "description": "The pagination token received from a previous [List import tasks](#tag/Import/operation/ListImports) request. Use this token to retrieve the next page of results.", "in": "query", "required": false, "type": "string" }, { "name": "pageSize", "description": "The maximum number of import tasks to return. If not specified, at most 10 node specs will be returned.", "in": "query", "required": false, "type": "integer", "format": "int32", "default": 10, "minimum": 1, "maximum": 100 }, { "name": "orderBy", "description": "Specifies the sorting order of results. Use a comma-separated list of field names, optionally appending `desc` for descending order. For example, `createTime, name desc`. By default, fields are sorted in ascending order.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Import" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports'" } ] }, "post": { "summary": "Create an import task", "description": "Creates an import task to import data into a cluster.", "operationId": "CreateImport", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1Import" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the target cluster where data will be imported.", "in": "path", "required": true, "type": "string" }, { "name": "import", "description": "The configuration details of the import task to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1beta1Import" } } ], "tags": [ "Import" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports' --header 'Content-Type: application/json' --data '{\n \"creationDetails\": {\n \"importOptions\": {\n \"fileType\": \"CSV\"\n },\n \"source\": {\n \"type\": \"S3\",\n \"s3\": {\n \"uri\": \"s3://{bucket_name}/{path_to_data}/\",\n \"authType\": \"ACCESS_KEY\",\n \"accessKey\": {\n \"id\": \"YOUR_ACCESS_KEY\",\n \"secret\": \"YOUR_SECRET_KEY\"\n }\n }\n }\n }\n}'" } ] } }, "/clusters/{clusterId}/imports/{importId}": { "get": { "summary": "Get an import task", "description": "Retrieves details of a specific import task by its ID.", "operationId": "GetImport", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta1Import" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster that contains the import task.", "in": "path", "required": true, "type": "string" }, { "name": "importId", "description": "The ID of the import task to retrieve.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Import" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports/{importId}'" } ] } }, "/clusters/{clusterId}/imports/{importId}:cancel": { "post": { "summary": "Cancel an import task", "description": "Cancels a running import task by its ID.", "operationId": "CancelImport", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster that contains the import task.", "in": "path", "required": true, "type": "string" }, { "name": "importId", "description": "The ID of the import task to cancel.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "description": "The ID of the import task." } } ], "tags": [ "Import" ], "x-code-samples": [ { "lang": "curl", "label": "curl", "source": "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request POST 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports/{importId}:cancel'" } ] } }, "/clusters/{clusterId}/integrations": { "get": { "summary": "List integrations", "description": "Lists all integrations configured for a cluster, including their current runtime status.", "operationId": "IntegrationService_ListIntegrations", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/openapiv1beta1ListIntegrationsResp" } }, "400": { "description": "A request field is invalid.", "schema": { "example": { "code": 400, "message": "Invalid request: missing or invalid field", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "example": { "code": 401, "message": "The API key cannot be authenticated.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "example": { "code": 403, "message": "The API key does not have permission to access the resource.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "example": { "code": 429, "message": "You have exceeded the rate limit.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "500": { "description": "Internal server error.", "schema": { "example": { "code": 500, "message": "Internal server error", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster to list integrations for.", "in": "path", "required": true, "type": "string", "format": "uint64" } ], "tags": [ "Integration" ], "x-codeSamples": [ { "label": "curl", "lang": "bash", "source": "curl -X GET \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations\" \\\n --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n -H \"Accept: application/json\"" } ] }, "post": { "summary": "Create an integration", "description": "Creates a new external metrics integration for the specified cluster. Supported integrations include [Datadog](https://www.datadoghq.com), [New Relic](https://newrelic.com), and [Prometheus](https://prometheus.io).", "operationId": "IntegrationService_CreateIntegration", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/openapiv1beta1IntegrationStatusResp" } }, "400": { "description": "A request field is invalid.", "schema": { "example": { "code": 400, "message": "Invalid request: missing or invalid field", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "example": { "code": 401, "message": "The API key cannot be authenticated.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "example": { "code": 403, "message": "The API key does not have permission to access the resource.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "example": { "code": 429, "message": "You have exceeded the rate limit.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "500": { "description": "Internal server error.", "schema": { "example": { "code": 500, "message": "Internal server error", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the target cluster where the integration will be created.", "in": "path", "required": true, "type": "string", "format": "uint64" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "example": { "type": "DATADOG", "datadog": { "api_key": "", "site": "US1" } }, "properties": { "type": { "description": "The service provider for the integration. Must be one of the supported values: `\"DATADOG\"`, `\"NEWRELIC\"`, or `\"PROMETHEUS\"`.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1IntegrationType" } ] }, "datadog": { "description": "The configuration for the Datadog integration. This is required when `type` is `\"DATADOG\"`.", "allOf": [ { "$ref": "#/definitions/v1beta1CreateDatadogIntegrationRequest" } ] }, "newrelic": { "description": "The configuration for the New Relic integration. This is required when `type` is `\"NEWRELIC\"`.", "allOf": [ { "$ref": "#/definitions/v1beta1CreateNewrelicIntegrationRequest" } ] }, "prometheus": { "description": "The configuration for the Prometheus integration. This is required when `type` is `\"PROMETHEUS\"`.", "allOf": [ { "$ref": "#/definitions/v1beta1CreatePrometheusMetricsKeyRequest" } ] } } } } ], "tags": [ "Integration" ], "x-codeSamples": [ { "label": "curl", "lang": "bash", "source": "curl -X POST \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations\" \\\n --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"DATADOG\",\n \"datadog\": {\n \"api_key\": \"\",\n \"site\": \"US1\"\n }\n }'" } ] } }, "/clusters/{clusterId}/integrations/{id}": { "delete": { "summary": "Delete an integration", "description": "Removes an integration from the cluster.", "operationId": "IntegrationService_DeleteIntegration", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "example": { "code": 400, "message": "Invalid request: missing or invalid field", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "example": { "code": 401, "message": "The API key cannot be authenticated.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "example": { "code": 403, "message": "The API key does not have permission to access the resource.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "example": { "code": 429, "message": "You have exceeded the rate limit.", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "500": { "description": "Internal server error.", "schema": { "example": { "code": 500, "message": "Internal server error", "details": [] }, "allOf": [ { "$ref": "#/definitions/rpcStatus" } ] } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster from which to delete the integration.", "in": "path", "required": true, "type": "string", "format": "uint64" }, { "name": "id", "description": "The ID of the integration to delete.", "in": "path", "required": true, "type": "string", "format": "uint64" } ], "tags": [ "Integration" ], "x-codeSamples": [ { "label": "curl", "lang": "bash", "source": "curl -X DELETE \"https://dedicated.tidbapi.com/v1beta1/clusters/123/integrations/456\" \\\n --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n -H \"Accept: application/json\"" } ] } }, "/changefeedRCUs": { "get": { "summary": "List changefeed RCU options", "description": "Lists the available changefeed RCU options that can be selected for a changefeed.", "operationId": "ListChangefeedRCUs", "responses": { "200": { "description": "The list of available changefeed RCU options.", "schema": { "$ref": "#/definitions/v1beta1ListChangefeedRCUsResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X GET \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeedRCUs'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X GET 'https://dedicated.tidbapi.com/v1beta1/changefeedRCUs'" } ] } }, "/changefeeds": { "get": { "summary": "List changefeeds", "description": "Lists the changefeeds for a cluster. Results can be filtered by downstream type and paginated using the page token.", "operationId": "ListChangefeeds", "responses": { "200": { "description": "The list of changefeeds matching the query.", "schema": { "$ref": "#/definitions/v1beta1ListChangefeedsResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster to list changefeeds for.", "in": "query", "required": true, "type": "string", "x-example": "1234567890123" }, { "name": "downstreamType", "description": "The downstream type to filter by. When not specified, returns all types.", "in": "query", "required": false, "type": "string", "enum": [ "DOWNSTREAM_TYPE_UNSPECIFIED", "KAFKA", "MYSQL", "S3", "GCS", "AZURE_BLOB" ], "default": "DOWNSTREAM_TYPE_UNSPECIFIED" }, { "name": "pageSize", "description": "The maximum number of changefeeds to return. The default value is 20.", "in": "query", "required": false, "type": "integer", "format": "int32", "x-example": 20 }, { "name": "pageToken", "description": "The page token from a previous ListChangefeeds response, used to retrieve the next page.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X GET \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds?clusterId=12345678901234567890'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X GET 'https://dedicated.tidbapi.com/v1beta1/changefeeds?clusterId=10534137955852385357'" } ] }, "post": { "summary": "Create a changefeed", "description": "Creates a changefeed to replicate data from a TiDB cluster to a downstream system. Supports Kafka, MySQL, S3, GCS, and Azure Blob downstream types.", "operationId": "CreateChangefeed", "responses": { "200": { "description": "The newly created changefeed.", "schema": { "$ref": "#/definitions/v1beta1Changefeed" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "body", "description": "The request for creating a changefeed.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1beta1CreateChangefeedRequest" } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"changefeed\": {\n \"clusterId\": \"12345678901234567890\",\n \"name\": \"my-changefeed-s3\",\n \"replicationCapacity\": \"4rcu\",\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"s3\": {\n \"endpoint\": {\n \"s3Uri\": \"s3://bucket_name/prefix/\",\n \"authType\": \"S3_AUTH_TYPE_AK_SK\",\n \"accessKey\": \"YOUR_ACCESS_KEY\",\n \"secretKey\": \"YOUR_SECRET_KEY\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CANAL_JSON\"\n }\n }\n },\n \"dryRun\": false\n}'", "label": "curl for s3" }, { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"changefeed\": {\n \"clusterId\": \"12345678901234567890\",\n \"name\": \"my-changefeed-mysql\",\n \"replicationCapacity\": \"4rcu\",\n \"downstreamType\": \"MYSQL\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"mysql\": {\n \"connection\": {\n \"endpoint\": \"your-mysql-host.example.com:3306\",\n \"username\": \"your_db_user\",\n \"password\": \"YOUR_DB_PASSWORD\"\n }\n }\n },\n \"dryRun\": false\n}'", "label": "curl for mysql" }, { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"changefeed\": {\n \"clusterId\": \"12345678901234567890\",\n \"name\": \"my-changefeed-kafka\",\n \"replicationCapacity\": \"4rcu\",\n \"downstreamType\": \"KAFKA\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"kafka\": {\n \"broker\": {\n \"version\": \"KAFKA_VERSION_2XX\",\n \"brokerEndpoints\": \"your-kafka-broker.example.com:9094\"\n },\n \"authentication\": {\n \"authType\": \"DISABLE\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CANAL_JSON\"\n },\n \"topicPartitionConfig\": {\n \"dispatchType\": \"DISPATCH_TYPE_ONE_TOPIC\",\n \"defaultTopic\": \"cdc-events\",\n \"replicationFactor\": 1,\n \"partitionNum\": 6\n }\n }\n },\n \"dryRun\": false\n}'", "label": "curl for kafka" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (S3)", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds' -d '{\n \"changefeed\": {\n \"clusterId\": \"10449877348102958363\",\n \"name\": \"my-changefeed-s3-aksk-02\",\n \"replicationCapacity\": \"4rcu\",\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"s3\": {\n \"endpoint\": {\n \"s3Uri\": \"s3://ticdc-test/cdc-api/s3-aksk-02/\",\n \"authType\": \"S3_AUTH_TYPE_AK_SK\",\n \"accessKey\": \"AKIA*******************\",\n \"secretKey\": \"********************************\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CANAL_JSON\"\n }\n }\n },\n \"dryRun\": false\n}'" }, { "lang": "curl", "label": "curl (MySQL)", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds' -d '{\n \"changefeed\": {\n \"clusterId\": \"10534137955852385357\",\n \"name\": \"my-changefeed-mysql-public\",\n \"replicationCapacity\": \"2rcu\",\n \"downstreamType\": \"MYSQL\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"mysql\": {\n \"connection\": {\n \"endpoint\": \"127.0.0.1:3306\",\n \"username\": \"********\",\n \"password\": \"********\"\n }\n }\n },\n \"dryRun\": false\n}'" }, { "lang": "curl", "label": "curl (Kafka)", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds' -d '{\n \"changefeed\": {\n \"clusterId\": \"10449877348102958363\",\n \"name\": \"my-changefeed-kafka-public\",\n \"replicationCapacity\": \"2rcu\",\n \"downstreamType\": \"KAFKA\",\n \"tableConfig\": {\n \"filterRules\": [\n \"*.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"kafka\": {\n \"broker\": {\n \"version\": \"KAFKA_VERSION_2XX\",\n \"brokerEndpoints\": \"0.0.0.0:9094\"\n },\n \"authentication\": {\n \"authType\": \"DISABLE\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CANAL_JSON\"\n },\n \"topicPartitionConfig\": {\n \"dispatchType\": \"DISPATCH_TYPE_ONE_TOPIC\",\n \"defaultTopic\": \"cdc-events\",\n \"replicationFactor\": 1,\n \"partitionNum\": 6\n }\n }\n },\n \"dryRun\": false\n}'" } ] } }, "/changefeeds/{changefeedId}": { "get": { "summary": "Get a changefeed", "description": "Gets the details of a changefeed by its ID, including its state, configuration, and checkpoint information.", "operationId": "GetChangefeed", "responses": { "200": { "description": "The changefeed details.", "schema": { "$ref": "#/definitions/v1beta1Changefeed" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to retrieve.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" }, { "name": "invalidateCache", "description": "Indicates whether to bypass the cache and return the real-time checkpoint information.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X GET \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X GET 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720'" } ] }, "delete": { "summary": "Delete a changefeed", "description": "Deletes a changefeed by its ID. This operation cannot be undone. The changefeed must be in a deletable state.", "operationId": "DeleteChangefeed", "responses": { "200": { "description": "The empty response indicating successful deletion.", "schema": { "type": "object", "properties": {} } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to delete.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X DELETE \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X DELETE 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720'" } ] } }, "/changefeeds/{changefeedId}:editDownstreamConfig": { "post": { "summary": "Update a changefeed downstream config", "description": "Updates the mutable configuration of an existing changefeed. The changefeed must be in the PAUSED state.", "operationId": "EditChangefeedDownstreamConfig", "responses": { "200": { "description": "The updated changefeed configuration.", "schema": { "$ref": "#/definitions/v1beta1Changefeed" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to update.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean", "example": true, "description": "Indicates whether to run dry-run validation only without applying the update." }, "tableConfig": { "description": "The updated table filtering and event filter configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1TableConfig" } ] }, "downstreamType": { "$ref": "#/definitions/v1beta1DownstreamType" }, "kafka": { "description": "The updated Kafka downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1KafkaDownstreamConfig" } ] }, "mysql": { "description": "The updated MySQL downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1MySQLDownstreamConfig" } ] }, "s3": { "description": "The updated S3 downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1S3DownstreamConfig" } ] }, "gcs": { "description": "The updated GCS downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1GcsDownstreamConfig" } ] }, "azureBlob": { "description": "The updated Azure Blob downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta1AzureBlobDownstreamConfig" } ] } }, "description": "The request for updating a changefeed downstream configuration.", "required": [ "downstreamType" ] }, "description": "The request for updating a changefeed downstream configuration." } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789:editDownstreamConfig' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"filterRules\": [\n \"test.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"dryRun\": false\n}'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720:editDownstreamConfig' -d '{\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"filterRules\": [\n \"test.*\"\n ],\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": true\n },\n \"dryRun\": false\n}'" } ] } }, "/changefeeds/{changefeedId}:pause": { "post": { "summary": "Pause a changefeed", "description": "Pauses a running changefeed. While paused, the changefeed stops replicating data but retains its configuration and checkpoint.", "operationId": "PauseChangefeed", "responses": { "200": { "description": "The empty response indicating the changefeed is pausing.", "schema": { "type": "object", "properties": {} } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to pause.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "description": "The request for pausing a changefeed." }, "description": "The request for pausing a changefeed." } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789:pause' \\\n -H 'Content-Type: application/json' \\\n -d '{ }'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720:pause' -d '{ }'" } ] } }, "/changefeeds/{changefeedId}:resume": { "post": { "summary": "Resume a changefeed", "description": "Resumes a paused changefeed. The changefeed continues replicating data from its last checkpoint.", "operationId": "ResumeChangefeed", "responses": { "200": { "description": "The empty response indicating the changefeed is resuming.", "schema": { "type": "object", "properties": {} } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to resume.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "description": "The request for resuming a changefeed." }, "description": "The request for resuming a changefeed." } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789:resume' \\\n -H 'Content-Type: application/json' \\\n -d '{ }'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720:resume' -d '{ }'" } ] } }, "/changefeeds/{changefeedId}:scale": { "post": { "summary": "Scale a changefeed", "description": "Scales a changefeed to a different replication capacity (RCU). The new capacity takes effect after the operation completes.", "operationId": "ScaleChangefeed", "responses": { "200": { "description": "The updated changefeed with the new replication capacity.", "schema": { "$ref": "#/definitions/v1beta1Changefeed" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "400": { "description": "The request is invalid. Check the request parameters." }, "401": { "description": "Authentication failed. Provide a valid API key." }, "403": { "description": "You do not have permission to perform this operation." }, "404": { "description": "The specified resource was not found." }, "429": { "description": "You have exceeded the rate limit. Retry after the specified period." }, "500": { "description": "An internal server error occurred. Contact support if the issue persists." } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to scale.", "in": "path", "required": true, "type": "string", "x-example": "cf-12345" }, { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "replicationCapacity": { "type": "string", "example": "8rcu", "description": "The target replication capacity (RCU) to scale to. Call ListChangefeedRCUs to get the available RCU options." } }, "description": "The request for scaling a changefeed.", "required": [ "replicationCapacity" ] }, "description": "The request for scaling a changefeed." } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "lang": "curl", "source": "curl \\\n -X POST \\\n 'https://dedicated.tidbapi.com/v1beta1/changefeeds/1234567890123456789:scale' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"replicationCapacity\": \"4rcu\"\n}'", "label": "curl" } ], "x-codeSamples": [ { "lang": "curl", "source": "curl -X POST 'https://dedicated.tidbapi.com/v1beta1/changefeeds/2068955910051614720:scale' -d '{\n \"replicationCapacity\": \"2rcu\"\n}'" } ] } } }, "definitions": { "tidb_cloud_open_apidedicatedv1beta1ListClustersResponse": { "type": "object", "properties": { "clusters": { "type": "array", "items": { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" }, "description": "A list of clusters that match the query." }, "totalSize": { "type": "integer", "format": "int32", "example": 1, "description": "The total number of clusters that match the query." }, "nextPageToken": { "type": "string", "example": "next_page_token", "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages." } } }, "tidb_cloud_open_apidedicatedv1beta1Cluster": { "type": "object", "properties": { "name": { "type": "string", "example": "clusters/1", "description": "The unique identifier for the TiDB cluster, which is generated by the API and follows the format `clusters/{clusterId}`.", "readOnly": true }, "clusterId": { "type": "string", "example": "1", "description": "The ID of the cluster.", "readOnly": true }, "displayName": { "type": "string", "example": "foo-bar", "description": "The user-defined name of the cluster.", "maxLength": 64, "minLength": 4, "pattern": "^[A-Za-z0-9][-A-Za-z0-9]{2,62}[A-Za-z0-9]$" }, "regionId": { "type": "string", "example": "aws-us-west-2", "description": "The region where the cluster is deployed, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`." }, "labels": { "type": "object", "example": { "tidb.cloud/project": "1" }, "additionalProperties": { "type": "string" }, "description": "Key-value pairs used to label the cluster. Each label consists of a string key and a string value. If the `tidb.cloud/project` label is not specified, the cluster is associated with the default project in the creator's organization. \n\n**Note**: Currently, only the `tidb.cloud/project` label key can be specified when creating a new cluster." }, "tidbNodeSetting": { "description": "The configuration for [TiDB nodes](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tidb-node) in a TiDB Cloud Dedicated cluster.\n\nTo view available node specs for a specific region and cloud provider, use the [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) endpoint.", "allOf": [ { "$ref": "#/definitions/v1beta1ClusterTidbNodeSetting" } ] }, "tikvNodeSetting": { "description": "The configuration for [TiKV nodes](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tikv-node) in a TiDB Cloud Dedicated cluster.\n\nTo view available node specs for a specific region and cloud provider, use the [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) endpoint.", "allOf": [ { "$ref": "#/definitions/v1beta1ClusterStorageNodeSetting" } ] }, "tiflashNodeSetting": { "example": { "nodeCount": 3, "nodeSpecKey": "16C128G", "storageSizeGi": 500, "storageType": "Basic" }, "description": "The configuration for [TiFlash nodes](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tiflash-node) in a TiDB Cloud Dedicated cluster. If not set, TiFlash is disabled.\n\nTo view available node specs for a specific region and cloud provider, use the [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) endpoint.", "allOf": [ { "$ref": "#/definitions/v1beta1ClusterStorageNodeSetting" } ] }, "port": { "type": "integer", "format": "int32", "example": 4000, "default": 4000, "description": "The port for cluster connections. All network endpoints in the cluster use this port.", "maximum": 65535, "minimum": 1024 }, "rootPassword": { "type": "string", "example": "my-shining-password", "description": "The root password of the cluster. It must be between 8 and 64 characters long and can contain letters, numbers, and special characters.", "maxLength": 64, "minLength": 8, "pattern": "^.{8,64}$" }, "state": { "example": "ACTIVE", "description": "The current state of the cluster.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/commonv1beta1ClusterState" } ] }, "version": { "type": "string", "example": "8.5.2", "description": "The TiDB version of the cluster.", "readOnly": true }, "createdBy": { "type": "string", "example": "test@example.com", "description": "The email address or public API key of the user who creates the cluster.", "readOnly": true }, "createTime": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z", "description": "The timestamp when the cluster was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "updateTime": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z", "description": "The timestamp when the cluster was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "pausePlan": { "description": "The pause plan configuration of the cluster.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1ClusterPausePlan" } ] }, "regionDisplayName": { "type": "string", "example": "N. Virginia (us-east-1)", "description": "The display name of the region where the cluster is located. For example, `N. Virginia (us-east-1)`.", "readOnly": true }, "cloudProvider": { "example": "aws", "description": "The cloud provider where the cluster is located.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1RegionCloudProvider" } ] }, "annotations": { "type": "object", "example": { "tidb.cloud/has-set-password": "false" }, "additionalProperties": { "type": "string" }, "description": "The annotations for the cluster. Each annotation consists of a string key and a string value. The following lists some predefined annotations:\n- `tidb.cloud/has-set-password`: indicates whether the cluster has a root password set.\n- `tidb.cloud/available-features`: lists available features of the cluster.\n- `tidb.cloud/insufficient-vm-resource`: indicates insufficient virtual machine resources during cluster creation or modification.", "readOnly": true } }, "description": "Cluster represents a dedicated TiDB cluster.", "required": [ "displayName", "regionId", "tidbNodeSetting", "tikvNodeSetting", "port" ] }, "v1beta1ClusterTidbNodeSetting": { "type": "object", "properties": { "nodeSpecKey": { "type": "string", "example": "8C32G", "description": "The node spec key of the TiDB nodes in the cluster. For example, `8C32G`. \n\nTo get the node spec available configurations of a specific region for a cloud provider, refer to [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) API." }, "tidbNodeGroups": { "type": "array", "items": { "$ref": "#/definitions/dedicatedv1beta1TidbNodeGroup" }, "description": "The [TiDB node groups](https://docs.pingcap.com/tidbcloud/tidb-node-group-overview/) in the cluster.\n\nWhen you create a cluster, this array must contain exactly one `TidbNodeGroup` object, and the `nodeCount` field must be set." }, "nodeSpecDisplayName": { "type": "string", "example": "8 vCPU, 32 GiB", "description": "The display name of the node spec. For example, `8 vCPU, 32 GiB`.", "readOnly": true } }, "required": [ "nodeSpecKey", "tidbNodeGroups" ] }, "dedicatedv1beta1TidbNodeGroup": { "type": "object", "properties": { "name": { "type": "string", "example": "tidbNodeGroups/1", "description": "The resource name of the TiDB node group, in the format of `tidbNodeGroups/{tidb_node_group_id}`.", "readOnly": true }, "tidbNodeGroupId": { "type": "string", "example": "1", "description": "The unique ID of the TiDB node group.", "readOnly": true }, "clusterId": { "type": "string", "example": "1", "description": "The ID of the cluster that the TiDB node group belongs to.\n\n- This field is **optional** when creating a cluster with the default TiDB node group.\n\n- This field is **required** when creating a non-default TiDB node group." }, "displayName": { "type": "string", "example": "DefaultGroup", "description": "The display name of the TiDB node group." }, "nodeCount": { "type": "integer", "format": "int32", "example": 2, "description": "The number of TiDB nodes in the TiDB node group. It must be greater than or equal to `1`.", "minimum": 1 }, "endpoints": { "type": "array", "example": [], "items": { "$ref": "#/definitions/dedicatedv1beta1TidbNodeGroupEndpoint" }, "description": "The endpoints of the TiDB node group.", "readOnly": true }, "nodeSpecKey": { "type": "string", "example": "8C32G", "description": "The node spec key of the TiDB node group. For example, `8C32G`.", "readOnly": true }, "nodeSpecDisplayName": { "type": "string", "example": "8 vCPU, 32 GiB", "description": "The display name of the node spec of the TiDB node group. For example, `8 vCPU, 32 GiB`.", "readOnly": true }, "isDefaultGroup": { "type": "boolean", "example": false, "description": "Indicates whether this is the default TiDB node group.", "readOnly": true }, "state": { "example": "ACTIVE", "description": "The current state of the TiDB node group.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1TidbNodeGroupState" } ] }, "nodeChangingProgress": { "description": "The progress of node configuration changes.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/ClusterNodeChangingProgress" } ] } }, "required": [ "nodeCount" ] }, "dedicatedv1beta1TidbNodeGroupEndpoint": { "type": "object", "properties": { "host": { "type": "string", "description": "The hostname or IP address of the endpoint. For `PRIVATE_ENDPOINT` connection types, availability varies by cloud provider:\n\n- For clusters deployed on AWS, the `host` field is available after the private link service is ready.\n\n- For clusters deployed on Google Cloud or Azure, the `host` field is available after you create a `PrivateEndpointConnection`.", "readOnly": true }, "port": { "type": "integer", "format": "int32", "description": "The port of the endpoint connection.", "readOnly": true }, "connectionType": { "example": "PRIVATE_ENDPOINT", "description": "The connection type for TiDB node group endpoints.\n\n- `\"PUBLIC\"`: indicates that the endpoint is accessible over the public network.\n\n- `\"VPC_PEERING\"`: indicates that the endpoint is accessible over [VPC peering](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#vpc-peering).\n\n- `\"PRIVATE_ENDPOINT\"`: indicates that the endpoint is accessible over a private link.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1TidbNodeGroupEndpointConnectionType" } ] } } }, "v1beta1TidbNodeGroupEndpointConnectionType": { "type": "string", "enum": [ "PUBLIC", "VPC_PEERING", "PRIVATE_ENDPOINT" ], "description": "The connection type for TiDB node group endpoints.\n\n - PUBLIC: Indicates that the endpoint is accessible over the public network.\n - VPC_PEERING: Indicates that the endpoint is accessible over [VPC peering](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#vpc-peering).\n - PRIVATE_ENDPOINT: Indicates that the endpoint is accessible over a private link." }, "dedicatedv1beta1TidbNodeGroupState": { "type": "string", "enum": [ "ACTIVE", "MODIFYING", "PAUSED" ], "description": " - ACTIVE: Indicates the TiDB node group is active and ready for use.\n - MODIFYING: Indicates the TiDB node group is being modified.\n - PAUSED: Indicates the TiDB node group is paused." }, "ClusterNodeChangingProgress": { "type": "object", "properties": { "matchingNodeSpecNodeCount": { "type": "integer", "format": "int32", "description": "The number of nodes that match the specified node spec.", "readOnly": true }, "remainingDeletionNodeCount": { "type": "integer", "format": "int32", "description": "The number of nodes pending deletion. This value appears only during node deletion operations.", "readOnly": true } } }, "v1beta1ClusterStorageNodeSetting": { "type": "object", "properties": { "nodeCount": { "type": "integer", "format": "int32", "example": 3, "description": "The number of nodes in the cluster." }, "nodeSpecKey": { "type": "string", "example": "8C32G", "description": "The node spec key of the nodes in the cluster. For example, `8C32G`." }, "storageSizeGi": { "type": "integer", "format": "int32", "example": 500, "description": "The storage size of each node in gibibytes (GiB). To view supported storage size ranges, use the [List node specs](#tag/Region/operation/RegionService_ListNodeSpecs) or [Get a node spec](#tag/Region/operation/RegionService_GetNodeSpec) endpoint." }, "storageType": { "example": "Standard", "description": "The storage type of the node. For more information, see [TiKV node storage types](https://docs.pingcap.com/tidbcloud/size-your-cluster/#tikv-node-storage-types) and [TiFlash node storage types](https://docs.pingcap.com/tidbcloud/size-your-cluster/#tiflash-node-storage-types).", "allOf": [ { "$ref": "#/definitions/StorageNodeSettingStorageType" } ] }, "raftStoreIops": { "type": "integer", "format": "int32", "x-nullable": true, "example": 3000, "description": "The IOPS (input/output operations per second) of the Raft store for the node. If not specified, the default IOPS of Raft store is used. It is recommended to leave it blank to use the default settings for optimal performance." }, "nodeSpecDisplayName": { "type": "string", "example": "8 vCPU, 32 GiB", "description": "The display name of the node spec. For example, `8 vCPU, 32 GiB`.", "readOnly": true }, "nodeChangingProgress": { "description": "The progress of the node changing.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/ClusterNodeChangingProgress" } ] } }, "required": [ "nodeCount", "nodeSpecKey", "storageSizeGi" ] }, "StorageNodeSettingStorageType": { "type": "string", "enum": [ "Basic", "Standard", "Performance", "Plus" ], "description": " - Basic: Data disk: gp3; Raft log disk: none.\n - Standard: Data disk: gp3; Raft log disk: gp3.\n - Performance: Data disk: gp3; Raft log disk: io2.\n - Plus: Data disk: io2; Raft log disk: none." }, "commonv1beta1ClusterState": { "type": "string", "enum": [ "CREATING", "DELETING", "ACTIVE", "RESTORING", "MAINTENANCE", "DELETED", "INACTIVE", "UPGRADING", "IMPORTING", "MODIFYING", "PAUSING", "PAUSED", "RESUMING" ], "description": "Enum of possible states of a cluster.\n\n - CREATING: Cluster is being created.\n - DELETING: Cluster is being deleted.\n - ACTIVE: Cluster is active for use.\n - RESTORING: Cluster data is being restored.\n - MAINTENANCE: Cluster is under maintenance.\n - DELETED: Cluster has been deleted.\n - INACTIVE: Cluster is not active, but not being deleted.\n - UPGRADING: Cluster is being updated.\nOnly for Dedicated Cluster.\n - IMPORTING: Cluster is being imported.\nOnly for Dedicated Cluster.\n - MODIFYING: Cluster is being modified.\nOnly for Dedicated Cluster.\n - PAUSING: Cluster is being paused.\nOnly for Dedicated Cluster.\n - PAUSED: Cluster is paused.\nOnly for Dedicated Cluster.\n - RESUMING: Cluster is resuming.\nOnly for Dedicated Cluster." }, "dedicatedv1beta1ClusterPausePlan": { "type": "object", "properties": { "pauseType": { "description": "The type of the pause plan.\n\n- `\"NORMAL\"`: the default pause plan.\n- `\"DEPRECATE\"`: the legacy pause plan and will be removed in a future release.", "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1ClusterPausePlanType" } ] }, "scheduledResumeTime": { "type": "string", "format": "date-time", "description": "The scheduled time for the cluster to automatically resume from the `PAUSED` state, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true } }, "required": [ "pauseType" ] }, "dedicatedv1beta1ClusterPausePlanType": { "type": "string", "enum": [ "NORMAL", "DEPRECATE" ], "description": "The type of the pause plan.\n\n- `NORMAL`: the default pause plan.\n- `DEPRECATE`: the legacy pause plan and will be removed in a future release." }, "v1beta1RegionCloudProvider": { "type": "string", "enum": [ "aws", "gcp", "azure", "alicloud" ], "description": "Enum of cloud provider names.\n\n - aws: Amazon Web Services.\n - gcp: Google Cloud Platform.\n - azure: Microsoft Azure.\n - alicloud: Alibaba Cloud." }, "googlerpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "description": "The error code returned with this error." }, "message": { "type": "string", "description": "The error message returned with this error." }, "details": { "type": "array", "items": { "$ref": "#/definitions/protobufAny" }, "description": "A list of messages with additional error details." } }, "description": "The `Status` type defines a logical error model that is suitable for\ndifferent programming environments, including REST APIs and RPC APIs. It is\nused by [gRPC](https://github.com/grpc). Each `Status` message contains\nthree pieces of data: error code, error message, and error details.\n\nYou can find out more about this error model and how to work with it in the\n[API Design Guide](https://cloud.google.com/apis/design/errors)." }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string", "description": "A URL or resource name that uniquely identifies the type of the serialized protocol buffer message." } }, "additionalProperties": {}, "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": ,\n \"lastName\": \n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" }, "v1beta1UpdateClusterRequestTidbNodeSetting": { "type": "object", "properties": { "nodeSpecKey": { "type": "string", "example": "8C32G", "description": "The node spec key of the TiDB nodes in the cluster. For example, `8C32G`. \n\nTo get the node spec available configurations of a specific region for a cloud provider, refer to [List node specs](#tag/Cluster/operation/RegionService_ListNodeSpecs) API." }, "tidbNodeGroups": { "type": "array", "items": { "$ref": "#/definitions/UpdateClusterRequestTidbNodeSettingTidbNodeGroup" }, "description": "The TiDB node groups of the cluster." } } }, "UpdateClusterRequestTidbNodeSettingTidbNodeGroup": { "type": "object", "properties": { "tidbNodeGroupId": { "type": "string", "example": "1", "description": "The ID of the TiDB node group. If empty, it means to scale the default TiDB node group." }, "nodeCount": { "type": "integer", "format": "int32", "x-nullable": true, "example": 2, "description": "The number of TiDB nodes in the TiDB node group. It must be greater than or equal to 1.", "minimum": 1 } } }, "v1beta1UpdateClusterRequestStorageNodeSetting": { "type": "object", "properties": { "nodeSpecKey": { "type": "string", "example": "8C32G", "description": "The node spec key of the nodes in the cluster. For example, `8C32G`." }, "nodeCount": { "type": "integer", "format": "int32", "x-nullable": true, "example": 3, "description": "The number of nodes in the cluster. \nWhen updating TiFlash node setting: \n- If the node count is set to 0, the TiFlash node will be removed.\n- If the node count is null, the TiFlash node count won't change.\nFor other components, if the node count is set to 0, server will ignore the node count." }, "storageSizeGi": { "type": "integer", "format": "int32", "example": 500, "description": "The storage size of the node in GiB. To get the supported storage size range, refer to the `NodeSpec` resource." }, "storageType": { "example": "Standard", "description": "The type of storage for the node. Defaults to `Basic`. For more information, see [TiKV node storage types](https://docs.pingcap.com/tidbcloud/size-your-cluster/#tikv-node-storage-types) and [TiFlash node storage types](https://docs.pingcap.com/tidbcloud/size-your-cluster/#tiflash-node-storage-types).", "allOf": [ { "$ref": "#/definitions/StorageNodeSettingStorageType" } ] }, "raftStoreIops": { "type": "integer", "format": "int32", "x-nullable": true, "example": 3000, "description": "The IOPS of the Raft store for the node. If not set, the default IOPS of Raft store will be used." } } }, "v1beta1PauseClusterResponse": { "type": "object", "properties": { "cluster": { "description": "The cluster details after it is paused.", "allOf": [ { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } ] } }, "required": [ "cluster" ] }, "v1beta1ResumeClusterResponse": { "type": "object", "properties": { "cluster": { "description": "The cluster details after it is resumed.", "allOf": [ { "$ref": "#/definitions/tidb_cloud_open_apidedicatedv1beta1Cluster" } ] } }, "required": [ "cluster" ] }, "dedicatedv1beta1ResetRootPasswordResponse": { "type": "object" }, "v1beta1ClusterServiceResetRootPasswordBody": { "type": "object", "properties": { "rootPassword": { "type": "string", "example": "new_password", "description": "The new root password for the cluster. The password must be between 8 and 64 characters long and can contain letters, numbers, and special characters." } }, "required": [ "rootPassword" ] }, "v1beta1ShowNodeQuotaResponse": { "type": "object", "properties": { "componentQuotas": { "type": "array", "example": [ { "componentType": "TIDB", "quota": 200 }, { "componentType": "TIKV", "quota": 200 }, { "componentType": "TIFLASH", "quota": 50 } ], "items": { "$ref": "#/definitions/ShowNodeQuotaResponseComponentQuota" }, "description": "A list of quotas for each component type. Each quota specifies the maximum number of nodes allowed for that component." } } }, "ShowNodeQuotaResponseComponentQuota": { "type": "object", "properties": { "componentType": { "description": "The component type. The value options are:\n\n- `TIDB`: [TiDB node](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tidb-node).\n\n- `TIKV`: [TiKV node](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tikv-node).\n\n- `TIFLASH`: [TiFlash node](https://docs.pingcap.com/tidbcloud/tidb-cloud-glossary/#tiflash-node).", "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1ComponentType" } ] }, "quota": { "type": "integer", "format": "int32", "description": "The maximum number of nodes allowed for this component type." } } }, "dedicatedv1beta1ComponentType": { "type": "string", "enum": [ "TIKV", "TIDB", "TIFLASH", "PD" ] }, "dedicatedv1beta1LogRedactionPolicy": { "type": "object", "properties": { "clusterId": { "type": "string", "example": "1", "description": "The ID of the cluster to which the log redaction policy applies." }, "redactLog": { "type": "boolean", "x-nullable": true, "example": true, "default": true, "description": "Indicates whether to redact sensitive information in logs.\n\nThe default policy is `true`, which means sensitive data is redacted in logs.\n\n**Note**: Disabling log redaction might expose sensitive information and increase the risk of data leakage. Ensure that you understand and acknowledge this risk before proceeding. Remember to re-enable it as soon as you complete your diagnostic or maintenance task." } }, "required": [ "clusterId" ] }, "tidb_cloud_open_apidedicatedv1beta1ListRegionsResponse": { "type": "object", "properties": { "regions": { "type": "array", "items": { "$ref": "#/definitions/commonv1beta1Region" }, "description": "A list of regions that match the query." }, "totalSize": { "type": "integer", "format": "int32", "description": "The total number of regions that match the query." }, "nextPageToken": { "type": "string", "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages." } } }, "commonv1beta1Region": { "type": "object", "properties": { "name": { "type": "string", "example": "regions/aws-us-west-2", "description": "The unique name of the region, in the format of `regions/{region_id}`. For example, `regions/aws-us-west-2`.", "pattern": "^regions/(aws|gcp|azure)-(.+)$" }, "regionId": { "type": "string", "example": "aws-us-west-2", "description": "The unique identifier for the region, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`.", "readOnly": true, "pattern": "^(aws|gcp|azure|alicloud)-[a-z0-9-]+$" }, "cloudProvider": { "example": "aws", "description": "The cloud provider that offers the region.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1RegionCloudProvider" } ] }, "displayName": { "type": "string", "example": "Oregon (us-west-2)", "description": "A human-readable name for the region. For example, `Oregon (us-west-2)`.", "readOnly": true }, "provider": { "type": "string", "x-nullable": true, "example": "aws", "description": "**Deprecated.** Use `cloudProvider` instead. The name of the cloud provider. For example, `aws`, `gcp`, `azure`, or `alicloud`.", "readOnly": true } }, "description": "A representation of a region for deploying TiDB clusters." }, "v1beta1ShowCloudProvidersResponse": { "type": "object", "properties": { "cloudProviders": { "type": "array", "items": { "$ref": "#/definitions/v1beta1RegionCloudProvider" }, "description": "A list of cloud providers that are available for the project.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud" } } }, "v1beta1ListNodeSpecsResponse": { "type": "object", "properties": { "nodeSpecs": { "type": "array", "items": { "$ref": "#/definitions/v1beta1NodeSpec" }, "description": "A list of node specs that match the query." }, "totalSize": { "type": "integer", "format": "int32", "description": "The total number of node specs that match the query." }, "nextPageToken": { "type": "string", "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages." } } }, "v1beta1NodeSpec": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the node spec resource, in the format of `regions/{region_id}/componentTypes/{component_type}/nodeSpecs/{node_spec_key}`. For example, `regions/aws-us-west-2/componentTypes/TIKV/nodeSpecs/8C32G`." }, "regionId": { "type": "string", "description": "The region ID of the node spec resource, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`." }, "componentType": { "description": "The component type of the node spec.", "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1ComponentType" } ] }, "nodeSpecKey": { "type": "string", "description": "The key of the node spec. For example, `8C32G`." }, "displayName": { "type": "string", "description": "The display name of the node spec. For example, `8 vCPU, 32 GiB`." }, "vCpu": { "type": "integer", "format": "int32", "description": "The number of virtual CPUs (vCPUs) allocated to the node spec. For example, `8`." }, "memorySizeGi": { "type": "integer", "format": "int32", "description": "The amount of memory in gibibytes (GiB) allocated to the node spec. For example, `32`." }, "defaultStorageSizeGi": { "type": "integer", "format": "int32", "description": "The default storage size of the node spec resource in GiB." }, "maxStorageSizeGi": { "type": "integer", "format": "int32", "description": "The maximum storage size of the node spec resource in GiB." }, "minStorageSizeGi": { "type": "integer", "format": "int32", "description": "The minimum storage size of the node spec resource in GiB." }, "defaultNodeCount": { "type": "integer", "format": "int32", "description": "The default number of nodes for the node spec resource." }, "storageTypes": { "type": "array", "items": { "$ref": "#/definitions/StorageNodeSettingStorageType" }, "description": "The storage types supported by the node spec resource." }, "maxRaftStoreIops": { "type": "integer", "format": "int32", "x-nullable": true, "description": "The maximum IOPS for Raft log storage of the node spec resource. Currently, this parameter is only useful when overriding IOPS for Raft log storage." }, "minRaftStoreIops": { "type": "integer", "format": "int32", "x-nullable": true, "description": "The minimum IOPS for Raft log storage of the node spec resource. Currently, this parameter is only useful when overriding IOPS for Raft log storage." }, "default": { "type": "boolean", "description": "Indicates whether this is the default node spec." } }, "description": "All fields are output only." }, "dedicatedv1beta1PrivateLinkService": { "type": "object", "properties": { "name": { "type": "string", "example": "tidbNodeGroups/1/privateLinkService", "description": "The name of the private link service." }, "tidbNodeGroupId": { "type": "string", "example": "1", "description": "The ID of the TiDB node group to which the private link service belongs." }, "serviceName": { "type": "string", "example": "com.amazonaws.vpce.us-east-1.vpce-svc-1234567890", "description": "The service name of the private link service, which varies by cloud provider:\n\n- AWS: the service name of the private link service.\n\n- Google Cloud: the resource name of the service attachment.\n\n- Azure: the resource ID of the private link service." }, "serviceDnsName": { "type": "string", "example": "privatelink-1234567890.muznnz1umf3p.clusters.tidb-cloud.com", "description": "The DNS name of the private link service, which varies by cloud provider:\n\n- AWS: the fully qualified domain name (FQDN) shared across all private endpoints, regardless of VPC location.\n\n- Google Cloud: the zone name (suffix of the FQDN) shared across all private endpoints in a single VPC network. The FQDN format is `.`.\n\n- Azure: the zone name shared across public internet. The FQDN format is `-.`." }, "availableZones": { "type": "array", "example": [ "use1-az1", "use1-az4", "use1-az6" ], "items": { "type": "string" }, "description": "(AWS only) The availability zones where the private link service is available. For more information, see [`DescribeVpcEndpointServices`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcEndpointServices.html)." }, "state": { "example": "ACTIVE", "description": "The state of the private link service.\n\n- `\"CREATING\"`: the private link service is being created.\n\n- `\"ACTIVE\"`: the private link service is ready to use.\n\n- `\"DELETING\"`: the private link service is being deleted.", "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1PrivateLinkServiceState" } ] }, "regionId": { "type": "string", "example": "aws-us-east-1", "description": "The ID of the region where the private link service is located, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`." }, "regionDisplayName": { "type": "string", "example": "N. Virginia (us-east-1)", "description": "The display name of the region where the private link service is located. For example, `N. Virginia (us-east-1)`." }, "cloudProvider": { "example": "aws", "description": "The cloud provider where the private link service is located.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud", "allOf": [ { "$ref": "#/definitions/v1beta1RegionCloudProvider" } ] } }, "description": "All fields are output only." }, "dedicatedv1beta1PrivateLinkServiceState": { "type": "string", "enum": [ "CREATING", "ACTIVE", "DELETING" ], "description": " - CREATING: The private link service is being created.\n - ACTIVE: The private link service is active and ready for use.\n - DELETING: The private link service is being deleted." }, "dedicatedv1beta1ListPrivateEndpointConnectionsResponse": { "type": "object", "properties": { "privateEndpointConnections": { "type": "array", "items": { "$ref": "#/definitions/dedicatedv1beta1PrivateEndpointConnection" }, "description": "A list of private endpoint connections that match the query." }, "totalSize": { "type": "integer", "format": "int32", "example": 1, "description": "The total number of private link connections that match the query." }, "nextPageToken": { "type": "string", "example": "next_page_token", "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages." } } }, "dedicatedv1beta1PrivateEndpointConnection": { "type": "object", "properties": { "name": { "type": "string", "example": "tidbNodeGroups/1/privateEndpointConnections/1234567890", "description": "The name of the private endpoint connection, in the format of `tidbNodeGroups/{tidb_node_group_id}/privateEndpointConnections/{private_endpoint_connection_id}`.", "readOnly": true }, "tidbNodeGroupId": { "type": "string", "example": "1", "description": "The ID of the TiDB node group to which the private endpoint connection belongs." }, "privateEndpointConnectionId": { "type": "string", "example": "1234567890", "description": "The unique ID of the private endpoint connection.", "readOnly": true }, "clusterId": { "type": "string", "example": "1", "description": "The ID of the cluster to which the private endpoint connection belongs.", "readOnly": true }, "clusterDisplayName": { "type": "string", "example": "my-cluster", "description": "The display name of the cluster to which the private endpoint connection belongs.", "readOnly": true }, "labels": { "type": "object", "example": { "tidb.cloud/project": "1" }, "additionalProperties": { "type": "string" }, "description": "The labels of the private link connection, including the mandatory `tidb.cloud/project` label identifying the project it belongs to. Each label consists of a string key and a string value.", "readOnly": true }, "endpointId": { "type": "string", "example": "vpce-0a1b2c3d4e5f6g7h8", "description": "The endpoint ID of the private link connection.\n\n- AWS: the VPC endpoint ID for [AWS PrivateLink\n](https://aws.amazon.com/privatelink/).\n\n- Google Cloud: the endpoint ID for [Private Service Connect](https://cloud.google.com/vpc/docs/private-service-connect).\n\n- Azure: the resource ID for [Azure Private Link](https://learn.microsoft.com/en-us/azure/private-link/private-link-overview)." }, "privateIpAddress": { "type": "string", "x-nullable": true, "description": "(Azure only) The private IP address of the private endpoint in your virtual network. TiDB Cloud automatically creates a public DNS record that resolves to this IP address, enabling you to connect using the DNS name." }, "endpointState": { "example": "ACTIVE", "description": "The state of the private endpoint connection.\n\n- `\"PENDING\"`: TiDB Cloud is asynchronously accepting the endpoint connection.\n\n- `\"ACTIVE\"`: the private endpoint connection is ready to use.\n\n- `\"DELETING\"`: the private endpoint connection is being deleted.\n\n- `\"FAILED\"`: the private endpoint connection has failed.\n- `\"DISCOVERED\"`: the endpoint is created in your VPC but not registered with TiDB Cloud.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1PrivateEndpointConnectionEndpointState" } ] }, "message": { "type": "string", "example": "", "description": "The detailed message when the `endpointState` field is `\"FAILED\"`.", "readOnly": true }, "regionId": { "type": "string", "example": "aws-us-east-1", "description": "The ID of the region where the private endpoint connection is located, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-east-1`.", "readOnly": true }, "regionDisplayName": { "type": "string", "example": "N. Virginia (us-east-1)", "description": "The display name of the region where the private endpoint connection is located. For example, `N. Virginia (us-east-1)`.", "readOnly": true }, "cloudProvider": { "example": "aws", "description": "The cloud provider where the private endpoint connection is located.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1RegionCloudProvider" } ] }, "privateLinkServiceName": { "type": "string", "example": "com.amazonaws.vpce.us-east-1.vpce-svc-1234567890", "description": "The name of the private link service that the private endpoint connection is connected to.", "readOnly": true }, "privateLinkServiceState": { "example": "ACTIVE", "description": "The state of the private link service that the private endpoint connection is connected to.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/dedicatedv1beta1PrivateLinkServiceState" } ] }, "tidbNodeGroupDisplayName": { "type": "string", "example": "DefaultGroup", "description": "The display name of the TiDB node group that the private endpoint connection is connected to.", "readOnly": true }, "accountId": { "type": "string", "x-nullable": true, "description": "(Google Cloud only) The project name used to identify the Google Cloud project that the private service connection belongs to.", "readOnly": true }, "host": { "type": "string", "example": "privatelink-1234567890.abcdefg.clusters.tidb-cloud.com", "description": "The hostname for accessing the TiDB cluster through the private endpoint connection.", "readOnly": true }, "port": { "type": "integer", "format": "int32", "example": 4000, "description": "The port used to connect to the TiDB cluster through the private endpoint connection.", "readOnly": true } }, "required": [ "tidbNodeGroupId", "endpointId" ] }, "dedicatedv1beta1PrivateEndpointConnectionEndpointState": { "type": "string", "enum": [ "PENDING", "ACTIVE", "DELETING", "FAILED", "DISCOVERED" ], "description": "The state of the private endpoint connection.\n\n- `\"PENDING\"`: TiDB Cloud is asynchronously accepting the endpoint connection.\n\n- `\"ACTIVE\"`: the private endpoint connection is ready to use.\n\n- `\"DELETING\"`: the private endpoint connection is being deleted.\n\n- `\"FAILED\"`: the private endpoint connection has failed.\n- `\"DISCOVERED\"`: the endpoint is created in your VPC but not registered with TiDB Cloud." }, "v1beta1ListImportsResponse": { "type": "object", "properties": { "imports": { "type": "array", "items": { "$ref": "#/definitions/v1beta1Import" }, "description": "The list of import tasks.", "readOnly": true }, "totalSize": { "type": "integer", "format": "int32", "example": 1, "description": "The total number of import tasks.", "readOnly": true }, "nextPageToken": { "type": "string", "example": "next_page_token", "description": "The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages.", "readOnly": true } }, "description": "The response message for listing imports." }, "v1beta1Import": { "type": "object", "properties": { "name": { "type": "string", "example": "clusters/1/imports/1", "description": "The name of the import task, in the format of `clusters/{cluster_id}/imports/{import_id}`.", "readOnly": true }, "clusterId": { "type": "string", "example": "1", "description": "The ID of the target cluster for the import.", "readOnly": true }, "totalSize": { "type": "string", "format": "int64", "example": 0, "description": "The total size of the data to be imported, in bytes.", "readOnly": true }, "createTime": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z", "description": "The timestamp when the import task was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "completeTime": { "type": "string", "format": "date-time", "example": "2023-10-01T12:01:00Z", "description": "The timestamp when the import task was completed, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "state": { "example": "COMPLETED", "description": "The state of the import task.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1ImportStateEnum" } ] }, "completePercent": { "type": "integer", "format": "int32", "example": 100, "minimum": 0, "maximum": 100, "description": "The percentage of import progress, excluding post-processing.", "readOnly": true }, "message": { "type": "string", "example": "", "description": "An error message if the import task failed. Otherwise, empty.", "readOnly": true }, "creator": { "type": "string", "example": "test@example.com", "description": "The email address of the user who creates the import task.", "readOnly": true }, "creationDetails": { "description": "The additional details about how the import task is created.", "allOf": [ { "$ref": "#/definitions/v1beta1CreationDetails" } ] }, "importId": { "type": "string", "example": "1", "description": "The unique identifier of the import task.", "readOnly": true } }, "description": "The import.", "required": [ "creationDetails" ] }, "v1beta1ImportStateEnum": { "type": "string", "enum": [ "UNSPECIFIED", "PREPARING", "IMPORTING", "COMPLETED", "FAILED", "CANCELING", "CANCELED" ], "default": "UNSPECIFIED", "description": "The state of the import.\n\n - UNSPECIFIED: Indicates that the import state is not specified.\n - PREPARING: Indicates that the import is being prepared.\n - IMPORTING: Indicates that the import is in progress.\n - COMPLETED: Indicates that the import is completed successfully.\n - FAILED: Indicates that the import has failed.\n - CANCELING: Indicates that the import is in the process of being canceled.\n - CANCELED: Indicates that the import has been canceled." }, "v1beta1CreationDetails": { "type": "object", "properties": { "importOptions": { "description": "The configuration options for the import task.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportOptions" } ] }, "source": { "description": "The data source for the import task.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportSource" } ] }, "targetTableInfos": { "type": "array", "items": { "$ref": "#/definitions/v1beta1ImportTargetTableInfo" }, "description": "A list of destination tables and their configurations for the import." }, "checkItems": { "type": "array", "example": [], "items": { "$ref": "#/definitions/v1beta1ImportValidationItem" }, "description": "A list of validation items that are checked during the import process." } }, "description": "The details of the import.", "required": [ "importOptions", "source" ] }, "v1beta1ImportOptions": { "type": "object", "properties": { "fileType": { "example": "CSV", "description": "The format of the file to import.\n\n- `\"CSV\"`: CSV files. For more information, see [Import CSV Files from Cloud Storage into TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/import-csv-files/).\n\n- `\"PARQUET\"`: Apache Parquet files. For more information, see [Import Apache Parquet Files from Cloud Storage into TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/import-parquet-files/).\n\n- `\"SQL\"`: SQL files.\n\n- `\"AURORA_SNAPSHOT\"`: Amazon Aurora snapshot files.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportFileTypeEnum" } ] }, "csvFormat": { "description": "The format specification for CSV files.", "allOf": [ { "$ref": "#/definitions/v1beta1CSVFormat" } ] }, "duplicationHandling": { "example": "REPLACE", "description": "Specifies how to handle duplicate records when importing SQL files.\n\n- `\"UNSPECIFIED\"`: the behavior is undefined.\n\n- `\"REPLACE\"`: existing rows are replaced with new data from the import file.\n\n- `\"IGNORE\"`: duplicate rows are skipped.\n\n- `\"ERROR\"`: the import fails if a duplicate row is found.", "allOf": [ { "$ref": "#/definitions/v1beta1DuplicationHandlingForSQLEnum" } ] }, "validateOnly": { "type": "boolean", "example": false, "description": "If set to `true`, the request is validated but not executed. Defaults to `false`." } }, "description": "The options of the import task.", "required": [ "fileType" ] }, "v1beta1ImportFileTypeEnum": { "type": "string", "enum": [ "UNSPECIFIED", "CSV", "SQL", "AURORA_SNAPSHOT", "PARQUET" ], "default": "UNSPECIFIED", "description": "The type of the file.\n\n - UNSPECIFIED: The type of the file is unknown.\n - CSV: CSV type.\n - SQL: SQL type.\n - AURORA_SNAPSHOT: Aurora snapshot type.\n - PARQUET: Parquet type." }, "v1beta1CSVFormat": { "type": "object", "properties": { "separator": { "type": "string", "example": ",", "default": ",", "description": "The character used to separate values in the CSV file." }, "delimiter": { "type": "string", "example": "\"", "default": "\"", "description": "The character used to enclose string values in the CSV file." }, "header": { "type": "boolean", "example": true, "default": true, "description": "Indicates whether the first row of the CSV file contains column headers." }, "notNull": { "type": "boolean", "example": false, "default": false, "description": "Indicates whether the columns in the CSV file can be NULL." }, "nullValue": { "type": "string", "example": "\\N", "default": "\\N", "description": "The string representation of NULL values in the CSV file." }, "backslashEscape": { "type": "boolean", "example": true, "default": true, "description": "Indicates whether to escape backslashes in the CSV file." }, "trimLastSeparator": { "type": "boolean", "example": false, "default": false, "description": "Indicates whether to remove trailing separators from each row in the CSV file." } }, "description": "The format of the CSV file." }, "v1beta1DuplicationHandlingForSQLEnum": { "type": "string", "enum": [ "UNSPECIFIED", "REPLACE", "IGNORE", "ERROR" ], "default": "UNSPECIFIED", "description": "The duplication handling for SQL.\n\n - UNSPECIFIED: The duplication handling for SQL is unknown.\n - REPLACE: The duplication handling for SQL is replace.\n - IGNORE: The duplication handling for SQL is ignore.\n - ERROR: The duplication handling for SQL is error." }, "v1beta1ImportSource": { "type": "object", "properties": { "type": { "example": "S3", "description": "The source from which data is imported.\n\nWhen this field is set, the corresponding configuration field must also be provided. For example, if type is `S3`, the `s3` field must be specified.\n\n- `\"UNSPECIFIED\"`: the import source is not specified.\n\n- `\"S3\"`: import from Amazon S3.\n\n- `\"GCS\"`: import from Google Cloud Storage.\n\n- `\"AZURE_BLOB\"`: import from Azure Blob Storage.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportSourceTypeEnum" } ] }, "s3": { "description": "The configuration details for importing from Amazon S3. This is required when `type` is `S3`.", "allOf": [ { "$ref": "#/definitions/v1beta1S3Source" } ] }, "gcs": { "description": "The configuration details for importing from Google Cloud Storage. This is required when `type` is `GCS`.", "allOf": [ { "$ref": "#/definitions/v1beta1GCSSource" } ] }, "azureBlob": { "description": "The configuration details for importing from Azure Blob Storage. This is required when `type` is `AZURE_BLOB`.", "allOf": [ { "$ref": "#/definitions/v1beta1AzureBlobSource" } ] } }, "description": "The source of the import.", "required": [ "type" ] }, "v1beta1ImportSourceTypeEnum": { "type": "string", "enum": [ "UNSPECIFIED", "S3", "GCS", "AZURE_BLOB" ], "default": "UNSPECIFIED", "description": "The source type of the import.\n\n - UNSPECIFIED: Indicates that the import source is not specified.\n - S3: Indicates that the import source is an AWS S3 resource.\n - GCS: Indicates that the import source is a Google Cloud Storage resource.\n - AZURE_BLOB: Indicates that the import source is an Azure Blob Storage resource." }, "v1beta1S3Source": { "type": "object", "properties": { "uri": { "type": "string", "example": "s3://bucket-name/path/", "description": "The S3 URI of the import source." }, "authType": { "example": "ROLE_ARN", "description": "The authentication method for accessing the S3 bucket.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportS3AuthTypeEnum" } ] }, "roleArn": { "type": "string", "example": "arn:aws:iam::123456789012:role/MyRole", "description": "The AWS IAM role ARN used for access. This is required when `authType` is set to `\"ROLE_ARN\"`." }, "accessKey": { "description": "The AWS access key credentials used for access. This is required when `authType` is set to `\"ACCESS_KEY\"`.", "allOf": [ { "$ref": "#/definitions/S3SourceAccessKey" } ] } }, "description": "The S3 source of the import.", "required": [ "uri", "authType" ] }, "v1beta1ImportS3AuthTypeEnum": { "type": "string", "enum": [ "UNSPECIFIED", "ROLE_ARN", "ACCESS_KEY" ], "default": "UNSPECIFIED", "description": "The type of the access method.\n\n - UNSPECIFIED: The access method is unknown.\n - ROLE_ARN: The access method is role arn.\n - ACCESS_KEY: The access method is access key." }, "S3SourceAccessKey": { "type": "object", "properties": { "id": { "type": "string", "example": "AKIAIOSFODNN7EXAMPLE", "description": "The access key ID for accessing the S3 source." }, "secret": { "type": "string", "example": "THESECRETKEY", "description": "The secret access key for accessing the S3 source. This field is input-only and not returned in responses." } }, "description": "The access key of the import source.", "required": [ "id", "secret" ] }, "v1beta1GCSSource": { "type": "object", "properties": { "uri": { "type": "string", "example": "gs://bucket-name/path/", "description": "The Google Cloud Storage URI of the import source." }, "authType": { "example": "SERVICE_ACCOUNT_KEY", "description": "The authentication method for accessing the Google Cloud Storage source.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportGcsAuthTypeEnum" } ] }, "serviceAccountKey": { "type": "string", "description": "The service account key for accessing the Google Cloud Storage source." } }, "description": "The Google Cloud Storage source of the import.", "required": [ "uri", "authType" ] }, "v1beta1ImportGcsAuthTypeEnum": { "type": "string", "enum": [ "UNSPECIFIED", "SERVICE_ACCOUNT_KEY" ], "default": "UNSPECIFIED", "description": "The type of the access method.\n\n - UNSPECIFIED: The access method is unknown.\n - SERVICE_ACCOUNT_KEY: The access method is service account key." }, "v1beta1AzureBlobSource": { "type": "object", "properties": { "authType": { "example": "SAS_TOKEN", "description": "The authentication method for accessing the Azure Blob Storage source.", "allOf": [ { "$ref": "#/definitions/v1beta1ImportAzureBlobAuthTypeEnum" } ] }, "sasToken": { "type": "string", "example": "?sv=2020-08-04&ss=b&srt=sco&sp=rwdlacup&se=2023-10-01T12:00:00Z&st=2023-09-30T12:00:00Z&spr=https&sig=example", "description": "The Shared Access Signature (SAS) token for accessing the Azure Blob Storage source. This field is input-only and not returned in responses." }, "uri": { "type": "string", "example": "azure://myaccount.blob.core.windows.net/mycontainer/mypath/", "description": "The Azure Blob Storage URI of the import source, in the format of `azure://.blob.core.windows.net//` or `https://.blob.core.windows.net//`." } }, "description": "The Azure Blob Storage source of the import.", "required": [ "authType", "uri" ] }, "v1beta1ImportAzureBlobAuthTypeEnum": { "type": "string", "enum": [ "UNSPECIFIED", "SAS_TOKEN" ], "default": "UNSPECIFIED", "description": "The type of the access method.\n\n - UNSPECIFIED: The access method is unknown.\n - SAS_TOKEN: The access method is sas token." }, "v1beta1ImportTargetTableInfo": { "type": "object", "properties": { "targetTable": { "description": "The target table where the data is imported.", "allOf": [ { "$ref": "#/definitions/commonTable" } ] }, "customFile": { "type": "string", "example": "s3://mybucket/myfolder/my-data1.csv", "description": "The custom file URI to import data into the target table. If not specified, TiDB Cloud Dedicated uses the default naming conventions to match files to tables." }, "matchedUri": { "type": "string", "description": "The actual source file URI that is matched to this table during import processing." } }, "description": "The target table info of the import task." }, "commonTable": { "type": "object", "properties": { "schema": { "type": "string", "example": "database_name", "description": "The name of the database containing the target table." }, "table": { "type": "string", "example": "table_name", "description": "The name of the table within the database." } } }, "v1beta1ImportValidationItem": { "type": "string", "enum": [ "IMPORT_VALIDATION_ITEM_UNSPECIFIED", "SOURCE_ACCESS_CHECK", "TARGET_ACCESS_CHECK", "FILTER_AND_RULE_CHECK", "IMPORT_PRECHECK", "TARGET_TABLE_EMPTY_CHECK", "ESTIMATE_SIZE", "IMPORT_DATA_ONLY_CHECK" ], "default": "IMPORT_VALIDATION_ITEM_UNSPECIFIED", "description": "The validation item of the import.\n\n - IMPORT_VALIDATION_ITEM_UNSPECIFIED: The validation item is unspecified.\n - SOURCE_ACCESS_CHECK: The validation item is source access check.\n - TARGET_ACCESS_CHECK: The validation item is target access check.(deprecated)\n - FILTER_AND_RULE_CHECK: The validation item is filter and rule check.(deprecated)\n - IMPORT_PRECHECK: The validation item is import precheck.\n - TARGET_TABLE_EMPTY_CHECK: The validation item is target table empty check.\n - ESTIMATE_SIZE: The validation item is estimate size.(deprecated)\n - IMPORT_DATA_ONLY_CHECK: The validation item is import data only check." }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/definitions/protobufAny" } } } }, "openapiv1beta1ListIntegrationsResp": { "type": "object", "example": { "items": [ { "id": 103, "type": "DATADOG", "datadog": { "state": "ACTIVE", "site": "US1", "masked_api_key": "****3086" }, "create_time": "2025-10-23T12:34:56Z", "update_time": "2025-10-24T08:21:00Z", "creator": "admin@example.com" } ], "total": 1 }, "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/openapiv1beta1IntegrationStatusResp" }, "description": "The list of integrations configured for the cluster." }, "total": { "type": "integer", "format": "int32", "description": "The total number of integrations configured for the cluster." } } }, "openapiv1beta1IntegrationStatusResp": { "type": "object", "example": { "id": 103, "type": "DATADOG", "datadog": { "state": "ACTIVE", "status_reason": "", "site": "US1", "site_url": "https://app.datadoghq.com", "dashboard_url": "https://app.datadoghq.com/dashboard/example", "masked_api_key": "****3086" }, "create_time": "2025-10-23T12:34:56Z", "update_time": "2025-10-24T08:21:00Z", "creator": "admin@example.com" }, "properties": { "id": { "type": "string", "format": "uint64", "description": "The unique identifier of the integration." }, "type": { "description": "The service provider for the integration.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1IntegrationType" } ] }, "datadog": { "description": "The configuration and status details for the Datadog integration.", "allOf": [ { "$ref": "#/definitions/v1beta1DatadogIntegrationStatusResp" } ] }, "newrelic": { "description": "The configuration and status details for the New Relic integration.", "allOf": [ { "$ref": "#/definitions/v1beta1NewrelicIntegrationStatusResp" } ] }, "prometheus": { "description": "The configuration and status details for the Prometheus integration.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1CreateMetricsKeyResp" } ] }, "createTime": { "type": "string", "format": "date-time", "description": "The timestamp when the integration was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format." }, "updateTime": { "type": "string", "format": "date-time", "description": "The timestamp when the integration was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format." }, "creator": { "type": "string", "description": "The email address or system identifier of the user who created the integration." } } }, "openapiv1beta1IntegrationType": { "type": "string", "enum": [ "DATADOG", "NEWRELIC", "PROMETHEUS" ] }, "v1beta1DatadogIntegrationStatusResp": { "type": "object", "example": { "state": "ACTIVE", "status_reason": "", "site": "US1", "site_url": "https://app.datadoghq.com", "dashboard_url": "https://app.datadoghq.com/dashboard/example", "masked_api_key": "****3086" }, "properties": { "state": { "description": "The current state of the Datadog integration.", "allOf": [ { "$ref": "#/definitions/v1beta1IntegrationState" } ] }, "statusReason": { "type": "string", "description": "A message describing the reason for an `ERROR` state. Empty when the integration is functioning normally." }, "site": { "description": "The Datadog site region where your cluster metrics are sent.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1DatadogSite" } ] }, "siteUrl": { "type": "string", "description": "The base URL of the Datadog site." }, "dashboardUrl": { "type": "string", "description": "A link to view your cluster metrics in Datadog." }, "maskedApiKey": { "type": "string", "description": "The API key used for the integration, which is partially masked." } } }, "v1beta1IntegrationState": { "type": "string", "enum": [ "NONE", "ACTIVE", "ERROR" ] }, "openapiv1beta1DatadogSite": { "type": "string", "enum": [ "US1", "US3", "US5", "EU1", "US1_FED", "AP1", "AP2" ] }, "v1beta1NewrelicIntegrationStatusResp": { "type": "object", "example": { "state": "ACTIVE", "status_reason": "", "site": "US_OTLP", "site_url": "https://one.newrelic.com", "dashboard_url": "https://one.newrelic.com/dashboard/example", "masked_api_key": "****abcd" }, "properties": { "state": { "description": "The current state of the New Relic integration.", "allOf": [ { "$ref": "#/definitions/v1beta1IntegrationState" } ] }, "statusReason": { "type": "string", "description": "A message describing the reason for an `ERROR` state. Empty when the integration is functioning normally." }, "site": { "description": "The New Relic ingestion site to use for metrics collection.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1NewrelicSite" } ] }, "siteUrl": { "type": "string", "description": "The base URL of the New Relic site." }, "dashboardUrl": { "type": "string", "description": "A link to view your cluster metrics in New Relic." }, "maskedApiKey": { "type": "string", "description": "The API key used for the integration, which is partially masked." } } }, "openapiv1beta1NewrelicSite": { "type": "string", "enum": [ "US_OTLP", "EU_OTLP" ] }, "openapiv1beta1CreateMetricsKeyResp": { "type": "object", "example": { "key": "", "query_endpoint": "https://prom.example.com/api/v1/query" }, "properties": { "key": { "type": "string", "description": "The generated read-only API key for authenticating Prometheus queries." }, "queryEndpoint": { "type": "string", "description": "The Prometheus-compatible HTTP endpoint for querying your cluster metrics." } } }, "v1beta1CreateDatadogIntegrationRequest": { "type": "object", "example": { "api_key": "", "site": "US1" }, "properties": { "apiKey": { "type": "string", "description": "The Datadog API key used to authenticate your integration. This field is write-only and will be masked in all responses." }, "site": { "description": "The Datadog site region where your cluster metrics are sent.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1DatadogSite" } ] } } }, "v1beta1CreateNewrelicIntegrationRequest": { "type": "object", "example": { "api_key": "", "site": "US_OTLP" }, "properties": { "apiKey": { "type": "string", "description": "The New Relic ingestion key used to connect your cluster to New Relic. This field is write-only and will be masked in all responses." }, "site": { "description": "The New Relic ingestion site where your cluster metrics are sent.", "allOf": [ { "$ref": "#/definitions/openapiv1beta1NewrelicSite" } ] } } }, "v1beta1CreatePrometheusMetricsKeyRequest": { "type": "object", "example": {} }, "AuthenticationAuthType": { "type": "string", "enum": [ "AUTH_TYPE_UNSPECIFIED", "DISABLE", "SASL_PLAIN", "SASL_SCRAM_SHA_256", "SASL_SCRAM_SHA_512" ], "default": "AUTH_TYPE_UNSPECIFIED", "description": "The Kafka authentication type.\n\n - `DISABLE`: No authentication.\n - `SASL_PLAIN`: SASL/PLAIN authentication.\n - `SASL_SCRAM_SHA_256`: SASL/SCRAM-SHA-256 authentication.\n - `SASL_SCRAM_SHA_512`: SASL/SCRAM-SHA-512 authentication." }, "AvroConfigBigintUnsignedHandlingMode": { "type": "string", "enum": [ "BIGINT_UNSIGNED_HANDLING_MODE_LONG", "BIGINT_UNSIGNED_HANDLING_MODE_STRING" ], "default": "BIGINT_UNSIGNED_HANDLING_MODE_LONG", "description": "The handling mode for BIGINT UNSIGNED values.\n\n - `BIGINT_UNSIGNED_HANDLING_MODE_LONG`: Use 64-bit integer (may overflow for very large values).\n - `BIGINT_UNSIGNED_HANDLING_MODE_STRING`: Use string representation (safe for all values)." }, "AvroConfigDecimalHandlingMode": { "type": "string", "enum": [ "DECIMAL_HANDLING_MODE_UNSPECIFIED", "DECIMAL_HANDLING_MODE_PRECISE", "DECIMAL_HANDLING_MODE_STRING" ], "default": "DECIMAL_HANDLING_MODE_UNSPECIFIED", "description": "The decimal serialization mode.\n\n - `DECIMAL_HANDLING_MODE_PRECISE`: Use precise decimal representation.\n - `DECIMAL_HANDLING_MODE_STRING`: Use string representation." }, "AvroConfigSchemaRegistry": { "type": "object", "properties": { "schemaRegistryEndpoints": { "type": "string", "example": "http://schema-registry:8081", "description": "The comma-separated list of Schema Registry endpoints. Required for Confluent Schema Registry." }, "enableBasicAuth": { "type": "boolean", "description": "Indicates whether to enable basic authentication for Schema Registry.", "example": false }, "basicAuthUsername": { "type": "string", "description": "The basic authentication username for Schema Registry." }, "basicAuthPassword": { "type": "string", "description": "The basic authentication password for Schema Registry." } }, "description": "The Schema Registry connection configuration." }, "ChangefeedState": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "RUNNING", "FAILED", "ERROR", "CREATING", "PAUSING", "PAUSED", "DELETING", "DELETED", "EDITING", "WARNING", "SCALING" ], "default": "STATE_UNSPECIFIED", "description": "The state of a changefeed.\n\n- `STATE_UNSPECIFIED`: Default value. Should not be used.\n- `RUNNING`: The changefeed is actively replicating data.\n- `FAILED`: The changefeed encountered a fatal error and stopped.\n- `ERROR`: The changefeed encountered an error but may recover.\n- `CREATING`: The changefeed is being created.\n- `PAUSING`: The changefeed is in the process of pausing.\n- `PAUSED`: The changefeed is paused.\n- `DELETING`: The changefeed is being deleted.\n- `DELETED`: The changefeed has been deleted.\n- `EDITING`: The changefeed configuration is being updated.\n- `WARNING`: The changefeed is running but has warnings.\n- `SCALING`: The changefeed is being scaled." }, "DataFormatAvroConfig": { "type": "object", "properties": { "decimalHandlingMode": { "example": "DECIMAL_HANDLING_MODE_PRECISE", "allOf": [ { "$ref": "#/definitions/AvroConfigDecimalHandlingMode" } ] }, "bigintUnsignedHandlingMode": { "example": "BIGINT_UNSIGNED_HANDLING_MODE_STRING", "allOf": [ { "$ref": "#/definitions/AvroConfigBigintUnsignedHandlingMode" } ] }, "schemaRegistry": { "$ref": "#/definitions/AvroConfigSchemaRegistry" } }, "description": "The Avro-specific data format configuration." }, "DataFormatDebeziumConfig": { "type": "object", "properties": { "outputOldValue": { "type": "boolean", "description": "Indicates whether to output the old value before the change." }, "disableSchema": { "type": "boolean", "description": "Indicates whether to disable the schema in Debezium messages." } }, "description": "The Debezium-specific data format configuration." }, "EndpointS3AuthType": { "type": "string", "enum": [ "S3_AUTH_TYPE_UNSPECIFIED", "S3_AUTH_TYPE_AK_SK", "S3_AUTH_TYPE_ASSUME_ROLE" ], "default": "S3_AUTH_TYPE_UNSPECIFIED", "description": "The S3 authentication type.\n\n - `S3_AUTH_TYPE_AK_SK`: Access Key / Secret Key authentication.\n - `S3_AUTH_TYPE_ASSUME_ROLE`: IAM Assume Role authentication." }, "KafkaDownstreamConfigAuthentication": { "type": "object", "properties": { "authType": { "example": "SASL_SCRAM_SHA_256", "allOf": [ { "$ref": "#/definitions/AuthenticationAuthType" } ] }, "username": { "type": "string", "description": "The SASL username for Kafka authentication." }, "password": { "type": "string", "description": "The SASL password for Kafka authentication." } }, "description": "The Kafka authentication configuration.", "required": [ "authType" ] }, "KafkaDownstreamConfigBroker": { "type": "object", "properties": { "version": { "example": "KAFKA_VERSION_3XX", "allOf": [ { "$ref": "#/definitions/KafkaDownstreamConfigKafkaVersion" } ] }, "brokerEndpoints": { "type": "string", "example": "broker1:9092,broker2:9092", "description": "The comma-separated list of Kafka broker addresses. Required for PUBLIC and VPC_PEERING network types. Not required for PRIVATE_LINK." }, "useTls": { "type": "boolean", "description": "Indicates whether to use TLS for the Kafka connection. The default value is false.", "example": false }, "insecureSkipVerify": { "type": "boolean", "description": "Indicates whether to skip TLS certificate verification. The default value is false.", "example": false }, "compression": { "example": "NONE", "allOf": [ { "$ref": "#/definitions/KafkaDownstreamConfigCompressionType" } ] } }, "description": "The Kafka broker connection configuration.", "required": [ "version" ] }, "KafkaDownstreamConfigColumnSelector": { "type": "object", "properties": { "matcher": { "type": "array", "items": { "type": "string" }, "description": "The table name patterns to match for column selection." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "The column names to include for the matched tables." } }, "description": "The column filtering configuration for specific tables." }, "KafkaDownstreamConfigCompressionType": { "type": "string", "enum": [ "COMPRESSION_TYPE_UNSPECIFIED", "NONE", "GZIP", "SNAPPY", "LZ4", "ZSTD" ], "default": "COMPRESSION_TYPE_UNSPECIFIED", "description": "The Kafka message compression type.\n\n - `NONE`: No compression.\n - `GZIP`: GZIP compression.\n - `SNAPPY`: Snappy compression.\n - `LZ4`: LZ4 compression.\n - `ZSTD`: ZSTD compression." }, "KafkaDownstreamConfigDataFormat": { "type": "object", "properties": { "protocol": { "example": "PROTOCOL_CANAL_JSON", "allOf": [ { "$ref": "#/definitions/KafkaDownstreamConfigDataFormatProtocol" } ] }, "debeziumConfig": { "$ref": "#/definitions/DataFormatDebeziumConfig" }, "avroConfig": { "$ref": "#/definitions/DataFormatAvroConfig" }, "enableTidbExtension": { "type": "boolean", "description": "Indicates whether to enable TiDB extension fields. The default value is false. For more information, see https://docs.pingcap.com/tidb/stable/ticdc-avro-protocol/#tidb-extension-fields.", "example": false }, "outputRawChangeEvent": { "type": "boolean", "description": "Indicates whether to output raw change events. The default value is false. For more information, see https://docs.pingcap.com/tidb/stable/ticdc-split-update-behavior/#split-update-events-for-mysql-sinks.", "example": false } }, "description": "The Kafka message format and serialization configuration.", "required": [ "protocol" ] }, "KafkaDownstreamConfigDataFormatProtocol": { "type": "string", "enum": [ "PROTOCOL_UNSPECIFIED", "PROTOCOL_CANAL_JSON", "PROTOCOL_OPEN_PROTOCOL", "PROTOCOL_AVRO", "PROTOCOL_DEBEZIUM" ], "default": "PROTOCOL_UNSPECIFIED", "description": "The Kafka output protocol.\n\n - `PROTOCOL_CANAL_JSON`: Canal JSON format. Recommended for most use cases.\n - `PROTOCOL_OPEN_PROTOCOL`: Open Protocol (TiDB native format).\n - `PROTOCOL_AVRO`: Apache Avro format.\n - `PROTOCOL_DEBEZIUM`: Debezium format." }, "KafkaDownstreamConfigKafkaVersion": { "type": "string", "enum": [ "KAFKA_VERSION_UNSPECIFIED", "KAFKA_VERSION_0XX", "KAFKA_VERSION_1XX", "KAFKA_VERSION_2XX", "KAFKA_VERSION_3XX" ], "default": "KAFKA_VERSION_UNSPECIFIED", "description": "The Kafka broker version.\n\n - `KAFKA_VERSION_0XX`: Kafka 0.x\n - `KAFKA_VERSION_1XX`: Kafka 1.x\n - `KAFKA_VERSION_2XX`: Kafka 2.x\n - `KAFKA_VERSION_3XX`: Kafka 3.x" }, "KafkaDownstreamConfigTopicPartitionConfig": { "type": "object", "properties": { "dispatchType": { "example": "DISPATCH_TYPE_BY_TABLE", "allOf": [ { "$ref": "#/definitions/TopicPartitionConfigDispatchType" } ] }, "defaultTopic": { "type": "string", "description": "The default topic for dispatching all messages when dispatchType is DISPATCH_TYPE_ONE_TOPIC." }, "topicPrefix": { "type": "string", "description": "The topic name prefix for dispatch types that create per-table or per-database topics." }, "separator": { "type": "string", "description": "The separator between the prefix and the table or database name." }, "topicSuffix": { "type": "string", "description": "The topic name suffix for dispatch types that create per-table or per-database topics." }, "replicationFactor": { "type": "integer", "format": "int64", "example": 3, "description": "The replication factor for auto-created topics.", "minimum": 1 }, "partitionNum": { "type": "integer", "format": "int64", "example": 6, "description": "The number of partitions for auto-created topics.", "minimum": 1 }, "partitionDispatchers": { "type": "array", "items": { "$ref": "#/definitions/TopicPartitionConfigPartitionDispatcherConfig" }, "description": "The custom partition dispatcher configurations." } }, "description": "The Kafka topic and partition configuration.", "required": [ "dispatchType", "replicationFactor", "partitionNum" ] }, "NetworkInfoNetworkType": { "type": "string", "enum": [ "NETWORK_TYPE_UNSPECIFIED", "NETWORK_TYPE_PUBLIC", "NETWORK_TYPE_VPC_PEERING", "NETWORK_TYPE_PRIVATE_LINK" ], "default": "NETWORK_TYPE_UNSPECIFIED", "description": "The network type for downstream connectivity.\n\n - `NETWORK_TYPE_UNSPECIFIED`: Default value.\n - `NETWORK_TYPE_PUBLIC`: Public internet access.\n - `NETWORK_TYPE_VPC_PEERING`: AWS VPC Peering.\n - `NETWORK_TYPE_PRIVATE_LINK`: Private endpoint connectivity managed by TiDB Cloud." }, "S3DataFormatBinaryEncodingMethod": { "type": "string", "enum": [ "BINARY_ENCODING_METHOD_UNSPECIFIED", "BASE64", "HEX" ], "default": "BINARY_ENCODING_METHOD_UNSPECIFIED", "description": "The binary encoding method.\n\n - `BASE64`: Base64 encoding.\n - `HEX`: Hexadecimal encoding." }, "S3DataFormatDateSeparator": { "type": "string", "enum": [ "DATE_SEPARATOR_UNSPECIFIED", "NONE", "YEAR", "MONTH", "DAY" ], "default": "DATE_SEPARATOR_UNSPECIFIED", "description": "The date separator for the directory structure.\n\n - `NONE`: No date separator.\n - `YEAR`: Separate by year.\n - `MONTH`: Separate by month.\n - `DAY`: Separate by day." }, "TopicPartitionConfigDispatchType": { "type": "string", "enum": [ "DISPATCH_TYPE_UNSPECIFIED", "DISPATCH_TYPE_ONE_TOPIC", "DISPATCH_TYPE_BY_TABLE", "DISPATCH_TYPE_BY_DATABASE" ], "default": "DISPATCH_TYPE_UNSPECIFIED", "description": "The message dispatch type to topics.\n\n - `DISPATCH_TYPE_ONE_TOPIC`: All messages go to a single topic.\n - `DISPATCH_TYPE_BY_TABLE`: Each table gets its own topic.\n - `DISPATCH_TYPE_BY_DATABASE`: Each database gets its own topic." }, "TopicPartitionConfigPartitionDispatcher": { "type": "string", "enum": [ "PARTITION_DISPATCHER_UNSPECIFIED", "TABLE", "INDEX_VALUE", "Timestamp", "COLUMNS" ], "default": "PARTITION_DISPATCHER_UNSPECIFIED", "description": "The partition dispatch strategy.\n\n - `TABLE`: Dispatch by table name.\n - `INDEX_VALUE`: Dispatch by index value.\n - `Timestamp`: Dispatch by timestamp.\n - `COLUMNS`: Dispatch by column values." }, "TopicPartitionConfigPartitionDispatcherConfig": { "type": "object", "properties": { "partitionType": { "example": "TABLE", "allOf": [ { "$ref": "#/definitions/TopicPartitionConfigPartitionDispatcher" } ] }, "matcher": { "type": "array", "items": { "type": "string" }, "description": "The table name patterns to match for the dispatcher." }, "indexName": { "type": "string", "description": "The index name for the INDEX_VALUE partition dispatcher." }, "columns": { "type": "array", "items": { "type": "string" }, "description": "The column names for the COLUMNS partition dispatcher." } }, "description": "The custom partition dispatcher configuration.", "required": [ "partitionType" ] }, "v1beta1AzureBlobDownstreamConfig": { "type": "object", "properties": { "endpoint": { "$ref": "#/definitions/v1beta1AzureBlobDownstreamConfigEndpoint" }, "dataFormat": { "$ref": "#/definitions/v1beta1S3DataFormat" }, "storageFlushConfig": { "$ref": "#/definitions/v1beta1StorageFlushConfig" } }, "description": "The Azure Blob downstream configuration.", "required": [ "endpoint", "dataFormat" ] }, "v1beta1AzureBlobDownstreamConfigEndpoint": { "type": "object", "properties": { "blobUri": { "type": "string", "example": "https://myaccount.blob.core.windows.net/mycontainer/cdc-data", "description": "The Azure Blob container URI. For example, `https://myaccount.blob.core.windows.net/mycontainer/cdc-data`." }, "sasToken": { "type": "string", "example": "sv=2022-11-02&ss=b&srt=sco&sp=rwdlaciytfx&se=2026-06-09T00:00:00Z&st=2026-06-08T00:00:00Z&spr=https&sig=...", "description": "The SAS token for Azure Blob authentication. This field is input-only and not returned in responses." } }, "description": "Endpoint defines the Azure Blob connection endpoint configuration.", "required": [ "blobUri", "sasToken" ] }, "v1beta1Changefeed": { "type": "object", "properties": { "id": { "type": "string", "example": "67890", "description": "The unique identifier of the changefeed. This field is output-only.", "readOnly": true }, "clusterId": { "type": "string", "example": "1234567890123", "description": "The ID of the source TiDB cluster." }, "name": { "type": "string", "example": "my-changefeed", "description": "The user-defined name of the changefeed." }, "networkInfo": { "$ref": "#/definitions/v1beta1NetworkInfo" }, "state": { "example": "RUNNING", "description": "The current state of the changefeed. This field is output-only.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/ChangefeedState" } ] }, "createTime": { "type": "string", "format": "date-time", "readOnly": true, "description": "The creation time of the changefeed. This field is output-only." }, "checkpointTso": { "type": "string", "format": "uint64", "readOnly": true, "description": "The checkpoint TSO of the changefeed. This field is output-only.", "example": "0" }, "checkpointTs": { "type": "string", "format": "date-time", "readOnly": true, "description": "The checkpoint timestamp of the changefeed. This field is output-only." }, "replicationCapacity": { "type": "string", "example": "4rcu", "description": "The replication capacity (RCU) of the changefeed. Call ListChangefeedRCUs to get the available RCU options." }, "downstreamType": { "description": "The downstream type. When a downstream type is specified, the corresponding configuration field (kafka, mysql, s3, gcs, or azureBlob) is required. Cannot be changed after creation.", "example": "KAFKA", "allOf": [ { "$ref": "#/definitions/v1beta1DownstreamType" } ] }, "tableConfig": { "$ref": "#/definitions/v1beta1TableConfig" }, "startPosition": { "description": "The start position configuration. This field can only be set during creation.", "allOf": [ { "$ref": "#/definitions/v1beta1StartPosition" } ] }, "kafka": { "$ref": "#/definitions/v1beta1KafkaDownstreamConfig" }, "mysql": { "$ref": "#/definitions/v1beta1MySQLDownstreamConfig" }, "s3": { "$ref": "#/definitions/v1beta1S3DownstreamConfig" }, "gcs": { "$ref": "#/definitions/v1beta1GcsDownstreamConfig" }, "azureBlob": { "$ref": "#/definitions/v1beta1AzureBlobDownstreamConfig" }, "error": { "type": "string", "example": "kafka: broker not available", "description": "The error message when the changefeed is in the FAILED or ERROR state.", "readOnly": true } }, "description": "The changefeed configuration.", "required": [ "clusterId", "name", "replicationCapacity", "downstreamType", "tableConfig", "startPosition" ] }, "v1beta1ChangefeedRCU": { "type": "object", "properties": { "name": { "type": "string", "example": "4rcu", "description": "The name of the RCU option.", "readOnly": true }, "displayName": { "type": "string", "example": "4 RCUs", "description": "The human-readable display name of the RCU option.", "readOnly": true }, "rcuNum": { "type": "integer", "format": "int64", "example": 4, "description": "The number of RCUs (Resource Capacity Units).", "readOnly": true }, "rpsLimit": { "type": "integer", "format": "int64", "example": 10000, "description": "The maximum rows per second for the RCU option. This value is for reference only and may vary by workload.", "readOnly": true } }, "description": "The changefeed RCU option." }, "v1beta1Connection": { "type": "object", "properties": { "endpoint": { "type": "string", "example": "mysql.example.com:3306", "description": "The MySQL endpoint address in the `host:port` format. For private endpoint connections, use networkInfo.sinkEndpointId instead. Required for PUBLIC and VPC_PEERING network types. Optional for PRIVATE_LINK, where the endpoint can be assembled from the sink endpoint and ports." }, "username": { "type": "string", "example": "root", "description": "The MySQL username for authentication." }, "password": { "type": "string", "example": "A1B2C3...", "description": "The MySQL password for authentication. This field is input-only and not returned in responses." } }, "description": "The MySQL connection configuration.", "required": [ "username" ] }, "v1beta1CreateChangefeedRequest": { "type": "object", "properties": { "changefeed": { "allOf": [ { "$ref": "#/definitions/v1beta1Changefeed" } ], "description": "The changefeed configuration to create." }, "dryRun": { "type": "boolean", "example": true, "description": "Indicates whether to run dry-run validation only without creating the changefeed." } }, "description": "The request for creating a changefeed.", "required": [ "changefeed" ] }, "v1beta1DownstreamType": { "type": "string", "enum": [ "DOWNSTREAM_TYPE_UNSPECIFIED", "KAFKA", "MYSQL", "S3", "GCS", "AZURE_BLOB" ], "default": "DOWNSTREAM_TYPE_UNSPECIFIED", "description": "The downstream type for a changefeed.\n\n - `KAFKA`: Apache Kafka.\n - `MYSQL`: MySQL-compatible database.\n - `S3`: Amazon S3 or S3-compatible storage.\n - `GCS`: Google Cloud Storage.\n - `AZURE_BLOB`: Azure Blob Storage." }, "v1beta1EventFilter": { "type": "object", "properties": { "tableMatchers": { "type": "array", "example": [ "mydb.orders", "mydb.user_*" ], "items": { "type": "string" }, "description": "The table name patterns to match. Uses the same syntax as TiCDC table filter. Supports wildcards. Matches database name, so be careful with database-level DDLs." }, "ignoredEvents": { "type": "array", "example": [ "insert", "delete", "alter table" ], "items": { "type": "string" }, "description": "The event types to ignore." }, "ignoredSqlStatements": { "type": "array", "example": [ "^drop", "add column" ], "items": { "type": "string" }, "description": "The SQL statement patterns to ignore. Only applies to DDL statements. Supports regular expressions." }, "ignoredInsertValueExpression": { "type": "string", "example": "status = 'deleted'", "description": "The SQL expression to filter INSERT events by column value. Uses SQL expressions in default SQL mode. All tables matched by `table_matchers` must contain all columns referenced." }, "ignoredUpdateOldValueExpression": { "type": "string", "example": "status = 'archived'", "description": "The SQL expression to filter UPDATE events by the old column value. Uses SQL expressions in default SQL mode. All tables matched by `table_matchers` must contain all columns referenced." }, "ignoredUpdateNewValueExpression": { "type": "string", "example": "status = 'deleted'", "description": "The SQL expression to filter UPDATE events by the new column value. Uses SQL expressions in default SQL mode. All tables matched by `table_matchers` must contain all columns referenced." }, "ignoredDeleteValueExpression": { "type": "string", "example": "soft_delete = true", "description": "The SQL expression to filter DELETE events by column value. Uses SQL expressions in default SQL mode. All tables matched by `table_matchers` must contain all columns referenced." } }, "description": "The event filter configuration for fine-grained control." }, "v1beta1GcsDownstreamConfig": { "type": "object", "properties": { "endpoint": { "$ref": "#/definitions/v1beta1GcsDownstreamConfigEndpoint" }, "dataFormat": { "$ref": "#/definitions/v1beta1S3DataFormat" }, "storageFlushConfig": { "$ref": "#/definitions/v1beta1StorageFlushConfig" } }, "description": "The GCS downstream configuration.", "required": [ "endpoint", "dataFormat" ] }, "v1beta1GcsDownstreamConfigEndpoint": { "type": "object", "properties": { "gcsUri": { "type": "string", "example": "gs://my-bucket/cdc-data", "description": "The GCS bucket URI. For example, `gs://my-bucket/cdc-data`." } }, "description": "The GCS endpoint configuration.", "required": [ "gcsUri" ] }, "v1beta1KafkaDownstreamConfig": { "type": "object", "properties": { "broker": { "$ref": "#/definitions/KafkaDownstreamConfigBroker" }, "authentication": { "$ref": "#/definitions/KafkaDownstreamConfigAuthentication" }, "dataFormat": { "$ref": "#/definitions/KafkaDownstreamConfigDataFormat" }, "topicPartitionConfig": { "$ref": "#/definitions/KafkaDownstreamConfigTopicPartitionConfig" }, "columnSelectors": { "type": "array", "items": { "$ref": "#/definitions/KafkaDownstreamConfigColumnSelector" }, "description": "The column selectors for filtering specific columns." } }, "description": "The Kafka downstream configuration.", "required": [ "broker", "authentication", "dataFormat", "topicPartitionConfig" ] }, "v1beta1ListChangefeedRCUsResponse": { "type": "object", "properties": { "rcus": { "type": "array", "items": { "$ref": "#/definitions/v1beta1ChangefeedRCU" }, "description": "The list of available RCU options.", "readOnly": true } }, "description": "The response for listing changefeed RCU options." }, "v1beta1ListChangefeedsResponse": { "type": "object", "properties": { "changefeeds": { "type": "array", "items": { "$ref": "#/definitions/v1beta1Changefeed" }, "description": "The list of changefeeds matching the query.", "readOnly": true }, "totalSize": { "type": "integer", "format": "int32", "example": 42, "description": "The total number of changefeeds across all pages.", "readOnly": true }, "nextPageToken": { "type": "string", "example": "eyJpZCI6Njc4OTB9", "description": "The page token for the next page. This field is empty when there are no more pages.", "readOnly": true } }, "title": "ListChangefeedsResponse represents the response for listing changefeeds\n(-- api-linter: core::0158::response-page-size-field=disabled --)\n(-- api-linter: core::0158::response-next-page-token-field=disabled --)", "description": "The response for listing changefeeds." }, "v1beta1MySQLDownstreamConfig": { "type": "object", "properties": { "connection": { "$ref": "#/definitions/v1beta1Connection" } }, "description": "The MySQL downstream configuration.", "required": [ "connection" ] }, "v1beta1NetworkInfo": { "type": "object", "properties": { "networkType": { "example": "NETWORK_TYPE_PUBLIC", "allOf": [ { "$ref": "#/definitions/NetworkInfoNetworkType" } ] }, "sinkEndpointId": { "type": "string", "format": "uint64", "description": "The private endpoint ID configured in the TiDB Cloud console. This field is required for PRIVATE_LINK network type." }, "ports": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "The downstream target ports to connect to for PRIVATE_LINK network type.", "example": [ 9092 ] } }, "description": "The network configuration for downstream connectivity.", "required": [ "networkType" ] }, "v1beta1S3DataFormat": { "type": "object", "properties": { "protocol": { "example": "PROTOCOL_CANAL_JSON", "allOf": [ { "$ref": "#/definitions/v1beta1S3DataFormatProtocol" } ] }, "terminator": { "type": "string", "description": "The row terminator used to separate data change events. This configuration is only used for storage sinks. The default value is \"\" (empty string), which means `\\r\\n` is used." }, "dateSeparator": { "description": "The date separator for the directory structure.\n\n- `NONE`: No date separator (default).\n- `YEAR`: Separate by year.\n- `MONTH`: Separate by month.\n- `DAY`: Separate by day.", "example": "DAY", "allOf": [ { "$ref": "#/definitions/S3DataFormatDateSeparator" } ] }, "enableTidbExtension": { "type": "boolean", "description": "Indicates whether to enable TiDB extension fields in Canal-JSON messages. The default value is false.", "example": false }, "delimiter": { "type": "string", "description": "The field delimiter for CSV files. The value must be an ASCII character. The default value is `,`." }, "quote": { "type": "string", "description": "The quotation character for CSV fields. The default value is `\"`. When the value is empty, no quotation is used." }, "null": { "type": "string", "description": "The null representation for CSV columns. The default value is `\\N`." }, "includeCommitTs": { "type": "boolean", "description": "Indicates whether to include the commit timestamp in CSV rows. The default value is false.", "example": false }, "binaryEncodingMethod": { "example": "BASE64", "allOf": [ { "$ref": "#/definitions/S3DataFormatBinaryEncodingMethod" } ] }, "outputRawChangeEvent": { "type": "boolean", "description": "Indicates whether to output raw change events. The default value is false. For more information, see https://docs.pingcap.com/tidb/stable/ticdc-split-update-behavior/#split-update-events-for-mysql-sinks.", "example": false }, "outputFieldHeader": { "type": "boolean", "description": "Indicates whether to include the CSV field header. The default value is false.", "example": false } }, "description": "The S3 data format configuration.", "required": [ "protocol" ] }, "v1beta1S3DataFormatProtocol": { "type": "string", "enum": [ "PROTOCOL_UNSPECIFIED", "PROTOCOL_CSV", "PROTOCOL_CANAL_JSON", "PROTOCOL_PARQUET" ], "default": "PROTOCOL_UNSPECIFIED", "description": "Protocol defines the supported output protocols for cloud storage sinks.\n\n - PROTOCOL_CSV: CSV format.\n - PROTOCOL_CANAL_JSON: Canal JSON format.\n - PROTOCOL_PARQUET: Apache Parquet format." }, "v1beta1S3DownstreamConfig": { "type": "object", "properties": { "endpoint": { "$ref": "#/definitions/v1beta1S3DownstreamConfigEndpoint" }, "dataFormat": { "$ref": "#/definitions/v1beta1S3DataFormat" }, "storageFlushConfig": { "$ref": "#/definitions/v1beta1StorageFlushConfig" } }, "description": "The S3 downstream configuration.", "required": [ "endpoint", "dataFormat" ] }, "v1beta1S3DownstreamConfigEndpoint": { "type": "object", "properties": { "s3Uri": { "type": "string", "example": "s3://bucket/prefix/", "description": "The S3 bucket URI. For example, `s3://bucket/prefix/`. The URI must end with a trailing slash." }, "authType": { "example": "S3_AUTH_TYPE_AK_SK", "allOf": [ { "$ref": "#/definitions/EndpointS3AuthType" } ] }, "accessKey": { "type": "string", "description": "The access key for S3 authentication. This field is required when authType is S3_AUTH_TYPE_AK_SK.", "example": "AKIA...A1B2C3" }, "secretKey": { "type": "string", "description": "The secret key for S3 authentication. This field is required when authType is S3_AUTH_TYPE_AK_SK. This field is input-only and not returned in responses.", "example": "A1B2C3..." }, "iamAssumedRoleArn": { "type": "string", "description": "The IAM assumed role ARN for S3 authentication. This field is required when authType is S3_AUTH_TYPE_ASSUME_ROLE.", "example": "arn:aws:iam::123456789012:role/redacted" } }, "description": "The S3 endpoint configuration.", "required": [ "s3Uri", "authType" ] }, "v1beta1StartPosition": { "type": "object", "properties": { "mode": { "example": "FROM_NOW", "allOf": [ { "$ref": "#/definitions/v1beta1StartPositionMode" } ] }, "startTso": { "type": "string", "format": "uint64", "description": "The start TSO. This field is required when the mode is FROM_TSO.", "example": "0" }, "startTimestamp": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "description": "The start UTC timestamp. This field is required when the mode is FROM_UTC." } }, "description": "The start position for the changefeed.", "required": [ "mode" ] }, "v1beta1StartPositionMode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "FROM_NOW", "FROM_TSO", "FROM_UTC" ], "default": "MODE_UNSPECIFIED", "description": "The start position mode.\n\n - `FROM_NOW`: Start from the current time.\n - `FROM_TSO`: Start from a specific TSO.\n - `FROM_UTC`: Start from a specific UTC timestamp." }, "v1beta1StorageFlushConfig": { "type": "object", "properties": { "interval": { "type": "string", "example": "1m", "description": "The flush interval. The range is from 2s to 10m. The default value is 1m." }, "fileSize": { "type": "string", "format": "uint64", "example": "67108864", "description": "The file size threshold in bytes. The range is from 1048576 (1 MB) to 536870912 (512 MB). The default value is 67108864 (64 MB).", "maximum": 536870912, "minimum": 1048576 } }, "description": "The storage flush configuration." }, "v1beta1TableConfig": { "type": "object", "properties": { "filterRules": { "type": "array", "items": { "type": "string" }, "description": "The table filter rules. Uses the TiCDC table filter syntax." }, "mode": { "example": "IGNORE_NOT_SUPPORT_TABLE", "allOf": [ { "$ref": "#/definitions/v1beta1TableConfigMode" } ] }, "caseSensitive": { "type": "boolean", "description": "Indicates whether the filter rules are case-sensitive." }, "eventFilters": { "type": "array", "items": { "$ref": "#/definitions/v1beta1EventFilter" }, "description": "The event filter rules for fine-grained control." } }, "description": "The table filtering and event filter configuration." }, "v1beta1TableConfigMode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "IGNORE_NOT_SUPPORT_TABLE", "FORCE_SYNC" ], "default": "MODE_UNSPECIFIED", "description": "The mode for handling unsupported tables.\n\n - `IGNORE_NOT_SUPPORT_TABLE`: Skip unsupported tables silently.\n - `FORCE_SYNC`: Force sync all tables (may fail on unsupported tables)." } } }