{ "swagger": "2.0", "info": { "title": "TiDB Cloud Premium API", "description": "*TiDB Cloud API is in beta.*\n\nThis API manages [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-premium) instances. For more information about TiDB Cloud API, see [TiDB Cloud API Overview](https://docs.pingcap.com/api/tidb-cloud-api-overview/).\n\n# Overview\n\nThe TiDB Cloud Premium API (v1beta2) provides [REST](https://en.wikipedia.org/wiki/REST) endpoints to manage TiDB Cloud Premium instances and related resources.\n\nYou can use this API to manage the following resources:\n\n- **TiDB Cloud Premium instance**: manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information.\n- **Backup**: manage backups for TiDB Cloud Premium instances, including backup-based restore.\n- **Changefeed**: manage the lifecycle and configuration of TiDB Cloud Premium changefeeds.\n- **Region**: retrieve available regions for deploying TiDB Cloud Premium instances.\n\n# Get Started\n\nThis guide helps you make your first API call to the TiDB Cloud Premium API. You will learn how to authenticate a request, build a request, and interpret the response.\n\n1. Create a [TiDB Cloud account](https://tidbcloud.com/signup) if you do not already have one.\n2. In the [TiDB Cloud console](https://tidbcloud.com/), go to **Organization** > **API Keys** and create an API key. For more information, see [API key management](#section/Authentication/API-key-management).\n3. Make your first API call.\n\n\tTo get all TiDB Cloud Premium instances in your organization, run the following command in your terminal. Replace `YOUR_PUBLIC_KEY` and `YOUR_PRIVATE_KEY` with your own key values.\n\n\t```bash\n\tcurl --digest \\\n\t --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n\t --request GET \\\n\t --url 'https://cloud.tidbapi.com/v1beta2/tidbs' \\\n\t --header 'Accept: application/json'\n\t```\n\n4. The API returns a JSON list of your TiDB Cloud Premium instances. If none exist, the response contains an empty list.\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# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud Premium API (v1beta2).\n\n\n\n## 20260908\n\n- Add the following changefeed endpoints for data replication from TiDB Cloud Premium to downstream systems, including Apache Kafka, MySQL, Amazon S3, and Alibaba Cloud OSS:\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* [Edit a changefeed](#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\t* [List changefeed CCU options](#tag/Changefeed/operation/ListChangefeedCapacityUnits)\n\n- Add the following endpoints for managing backups:\n\t* [Create a backup for a TiDB Cloud Premium instance](#tag/Backup/operation/TidbService_CreateTidbBackup)\n\n## 20260609\n\n- Add the following endpoint for managing backups:\n\t* [List backups](#tag/Backup/operation/BackupService_ListBackups)\n\t* [Delete a backup](#tag/Backup/operation/BackupService_DeleteBackup)\n\n## 20260428\n\n- Initial release of the TiDB Cloud Premium API (v1beta2), including the following resources and endpoints:\n\t* TiDB Cloud Premium instance\n\t\t* [List TiDB Cloud Premium instances](#tag/TiDB-Instance/operation/TidbService_ListTidbs)\n\t\t* [Create a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_CreateTidb)\n\t\t* [Get a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_GetTidb)\n\t\t* [Delete a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_DeleteTidb)\n\t\t* [Update a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_UpdateTidb)\n\t\t* [Reset the root password of a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_ResetRootPassword)\n\t\t* [Get cloud provider information for a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_GetCloudProviderInfo)\n\t\t* [Get the CA certificate download URL for a TiDB Cloud Premium instance](#tag/TiDB-Instance/operation/TidbService_GetCaCertificateDownloadUrl)\n\t* Backup\n\t\t* [List backups for a TiDB Cloud Premium instance](#tag/Backup/operation/TidbService_ListTidbBackups)\n\t\t* [Delete a backup for a TiDB Cloud Premium instance](#tag/Backup/operation/TidbService_DeleteTidbBackup)\n\t\t* [Restore a TiDB Cloud Premium instance from a backup](#tag/Backup/operation/TidbService_RestoreTidb)\n\t\t* [Get restore status for a TiDB Cloud Premium instance](#tag/Backup/operation/TidbService_GetRestoreStatus)\n\t* Region\n\t\t* [List regions](#tag/Region/operation/RegionService_ListRegions)\n", "version": "v1beta2" }, "tags": [ { "name": "TiDB Cloud Premium Instance", "description": "Manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information." }, { "name": "Backup", "description": "Manage backups for TiDB Cloud Premium instances, including backup-based restore." }, { "name": "Region", "description": "Retrieve available regions for deploying TiDB Cloud Premium instances." }, { "name": "Changefeed", "description": "Manage the lifecycle and configuration of TiDB Cloud Premium changefeeds." } ], "host": "cloud.tidbapi.com", "basePath": "/v1beta2", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/tidbs": { "get": { "summary": "List TiDB Cloud Premium instances", "description": "Lists all TiDB Cloud Premium instances in your organization. You can filter results by service plan, region, name, or ID.", "operationId": "TidbService_ListTidbs", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListTidbsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "servicePlan", "description": "The plan of the service. If specified, only TiDB Cloud Premium instances of the specified plan are returned.\n\n- `Premium`: [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-premium)", "in": "query", "required": false, "type": "string", "enum": [ "Premium" ] }, { "name": "regionIds", "description": "A list of region IDs. If specified, only TiDB Cloud Premium instances in these regions are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "name", "description": "The display name to filter by. If specified, only TiDB Cloud Premium instances whose display name contains this value are returned.", "in": "query", "required": false, "type": "string" }, { "name": "tags", "description": "A list of tags. If specified, only TiDB Cloud Premium instances tagged with any of these values are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "tidbIds", "description": "A list of TiDB Cloud Premium instance IDs. If specified, only the ones matching these IDs are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "pageSize", "description": "The maximum number of TiDB Cloud Premium instances to return. If not specified, at most 10 will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.", "in": "query", "required": false, "type": "integer", "format": "int32", "default": "10" }, { "name": "pageToken", "description": "The pagination token received from a previous [List TiDB Cloud Premium instances](#tag/TiDB-Instance/operation/TidbService_ListTidbs) 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 TiDB Cloud Premium instances to skip before returning results. If the value exceeds the total number of TiDB Cloud Premium instances, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] }, "post": { "summary": "Create a TiDB Cloud Premium instance", "description": "Creates a new TiDB Cloud Premium instance. If the `tidb.cloud/project` label is provided, the instance will be created in the specified project.", "operationId": "TidbService_CreateTidb", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/nextgenv1beta2Tidb" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidb", "description": "The TiDB Cloud Premium instance to create.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/nextgenv1beta2Tidb" } }, { "name": "validateOnly", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"displayName\": \"my-tidb\",\n \"regionId\": \"aws-us-west-2\",\n \"maxRcu\": 20000,\n \"servicePlan\": \"Premium\"\n}'" } ] } }, "/tidbs/{tidbId}": { "get": { "summary": "Get a TiDB Cloud Premium instance", "description": "Retrieves details of a specific TiDB Cloud Premium instance.", "operationId": "TidbService_GetTidb", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/nextgenv1beta2Tidb" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance to retrieve.", "in": "path", "required": true, "type": "string" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] }, "delete": { "summary": "Delete a TiDB Cloud Premium instance", "description": "Deletes a TiDB Cloud Premium instance by `tidbId`.", "operationId": "TidbService_DeleteTidb", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/nextgenv1beta2Tidb" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance 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": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/tidbs/{tidb.tidbId}": { "patch": { "summary": "Update a TiDB Cloud Premium instance", "description": "Updates the configuration of a specific TiDB Cloud Premium instance. You can modify the following fields: `displayName` and `maxRcu`.", "operationId": "TidbService_UpdateTidb", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/nextgenv1beta2Tidb" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidb.tidbId", "description": "The ID of the TiDB Cloud Premium instance to update.", "in": "path", "required": true, "type": "string" }, { "name": "tidb", "description": "The TiDB Cloud Premium instance to update.", "in": "body", "required": true, "schema": { "type": "object", "properties": { "displayName": { "type": "string", "example": "foo-bar", "description": "The user-defined name of the TiDB Cloud Premium instance.", "maxLength": 64, "minLength": 4, "pattern": "^[A-Za-z0-9][-A-Za-z0-9]{2,62}[A-Za-z0-9]$" }, "minRcu": { "type": "string", "format": "int64", "description": "Deprecated: min_rcu is now automatically managed.\nAny value provided here will be ignored in favor of max(5000, max_rcu / 4).", "readOnly": true }, "maxRcu": { "type": "string", "format": "int64", "description": "The maximum number of Request Capacity Units (RCUs) for the TiDB Cloud Premium instance." } }, "title": "The TiDB Cloud Premium instance to update.", "required": [ "tidb" ] } }, { "name": "validateOnly", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`.", "in": "query", "required": false, "type": "boolean" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request PATCH 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"displayName\": \"my-updated-tidb\",\n \"maxRcu\": 40000\n}'" } ] } }, "/tidbs/{tidbId}:resetRootPassword": { "post": { "summary": "Reset the root password of a TiDB Cloud Premium instance", "description": "Sets a new password for the TiDB Cloud Premium instance's root user. The new password is not returned in the response for security reasons, so save your password in a secure location.", "operationId": "TidbService_ResetRootPassword", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ResetRootPasswordResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to reset the root password.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/TidbServiceResetRootPasswordBody" } } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}:resetRootPassword' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"rootPassword\": \"your-new-password\"\n}'" } ] } }, "/tidbs/{tidbId}/cloudProviderInfo": { "get": { "summary": "Get cloud provider information for a TiDB Cloud Premium instance", "description": "Retrieves the TiDB Cloud account ID and external ID for the underlying cloud infrastructure of a specific TiDB Cloud Premium instance.", "operationId": "TidbService_GetCloudProviderInfo", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2CloudProviderInfo" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to retrieve cloud provider information.", "in": "path", "required": true, "type": "string" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/cloudProviderInfo' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/tidbs/{tidbId}/backups": { "get": { "summary": "List backups for a TiDB Cloud Premium instance", "description": "Lists all backups for a specific TiDB Cloud Premium instance. You can filter results by state, region, trigger type, or time range.", "operationId": "TidbService_ListTidbBackups", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListTidbBackupsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to list backups.", "in": "path", "required": true, "type": "string" }, { "name": "states", "description": "A list of backup states. If specified, only backups matching these states are returned.\n\n - UNKNOWN: The backup state is unknown.\n - PENDING: The backup is pending.\n - RUNNING: The backup is in progress.\n - SUCCEEDED: The backup completed successfully.\n - FAILED: The backup has failed.\n - CANCELLED: The backup is cancelled.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELLED" ] }, "collectionFormat": "multi" }, { "name": "regionIds", "description": "A list of region IDs. If specified, only backups in these regions are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "triggerTypes", "description": "A list of backup trigger types. If specified, only backups matching these trigger types are returned.\n\n - AUTO: The backup is triggered automatically by TiDB Cloud.\n - MANUAL: The backup is triggered manually by a user.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "AUTO", "MANUAL" ] }, "collectionFormat": "multi" }, { "name": "startTime", "description": "The inclusive start of the backup time range, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If specified, only backups at or after this time are returned.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "endTime", "description": "The inclusive end of the backup time range, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If specified, only backups at or before this time are returned.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "pageSize", "description": "The maximum number of backups to return. If not specified, at most 10 backups will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.", "in": "query", "required": false, "type": "integer", "format": "int32", "default": "10" }, { "name": "pageToken", "description": "The pagination token received from a previous [List backups for a TiDB Cloud Premium instance](#tag/Backup/operation/TidbService_ListTidbBackups) 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 backups to skip before returning results. If the value exceeds the total number of backups, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/backups' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] }, "post": { "summary": "Create a backup for a TiDB Cloud Premium instance", "description": "Creates a manual backup for a specific TiDB Cloud Premium instance.", "operationId": "TidbService_CreateTidbBackup", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2CreateTidbBackupResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to create a backup.", "in": "path", "required": true, "type": "string" }, { "name": "body", "description": "The request for creating a manual backup.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/TidbServiceCreateTidbBackupBody" } } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/backups' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"name\": \"my-manual-backup\"\n}'" } ] } }, "/tidbs/{tidbId}/backups/{backupId}": { "delete": { "summary": "Delete a backup for a TiDB Cloud Premium instance", "description": "Deletes a backup by `backupId`.", "operationId": "TidbService_DeleteTidbBackup", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance.", "in": "path", "required": true, "type": "string" }, { "name": "backupId", "description": "The ID of the backup to delete.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/backups/{backup_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/tidbs:restore": { "post": { "summary": "Restore a TiDB Cloud Premium instance from a backup", "description": "Restores a new TiDB Cloud Premium instance from a backup. Supported restore modes: `SNAPSHOT`, `PITR`, `DEDICATED_SNAPSHOT`, and `CLASSIC_SNAPSHOT`.", "operationId": "TidbService_RestoreTidb", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2RestoreTidbResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1beta2RestoreTidbRequest" } } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl (SNAPSHOT)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs:restore' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"tidb\": {\n \"displayName\": \"my-restored-tidb\",\n \"regionId\": \"aws-us-west-2\",\n \"maxRcu\": 20000,\n \"servicePlan\": \"Premium\"\n },\n \"sourceTidbId\": \"{source_tidb_id}\",\n \"restoreMode\": \"SNAPSHOT\",\n \"backupId\": \"{backup_id}\"\n}'" }, { "label": "curl (PITR)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs:restore' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"tidb\": {\n \"displayName\": \"my-restored-tidb\",\n \"regionId\": \"aws-us-west-2\",\n \"maxRcu\": 20000,\n \"servicePlan\": \"Premium\"\n },\n \"sourceTidbId\": \"{source_tidb_id}\",\n \"restoreMode\": \"PITR\",\n \"pointInTime\": \"2023-10-01T12:00:00Z\"\n}'" }, { "label": "curl (DEDICATED_SNAPSHOT)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs:restore' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"tidb\": {\n \"displayName\": \"my-restored-tidb\",\n \"regionId\": \"aws-us-west-2\",\n \"maxRcu\": 20000,\n \"servicePlan\": \"Premium\"\n },\n \"sourceTidbId\": \"{source_tidb_id}\",\n \"restoreMode\": \"DEDICATED_SNAPSHOT\",\n \"backupId\": \"{backup_id}\"\n}'" }, { "label": "curl (CLASSIC_SNAPSHOT)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs:restore' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"tidb\": {\n \"displayName\": \"my-restored-tidb\",\n \"regionId\": \"aws-us-west-2\",\n \"maxRcu\": 20000,\n \"servicePlan\": \"Premium\"\n },\n \"restoreMode\": \"CLASSIC_SNAPSHOT\",\n \"classicBackupStorage\": {\n \"cloudProvider\": \"aws\",\n \"bucketUri\": \"s3://my-backup-bucket/tidb-backups/\",\n \"auth\": {\n \"accessKeyId\": \"AKIAIOSFODNN7EXAMPLE\",\n \"accessKeySecret\": \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\"\n }\n }\n}'" } ] } }, "/tidbs/{tidbId}:getRestoreStatus": { "get": { "summary": "Get the restore status for a TiDB Cloud Premium instance", "description": "Retrieves the restore progress of a TiDB Cloud Premium instance, including the completion percentage and any error messages.", "operationId": "TidbService_GetRestoreStatus", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2GetRestoreStatusResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}:getRestoreStatus' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/tidbs/{tidbId}/caCertificateUrl": { "get": { "summary": "Get the CA certificate download URL for a TiDB Cloud Premium instance", "description": "Retrieves the download URL for the CA certificate required to establish TLS (Transport Layer Security) connections to a specific TiDB Cloud Premium instance.", "operationId": "TidbService_GetCaCertificateDownloadUrl", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2CaCertificateDownloadUrl" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to retrieve the CA certificate.", "in": "path", "required": true, "type": "string" } ], "tags": [ "TiDB Cloud Premium Instance" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/tidbs/{tidb_id}/caCertificateUrl' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/backups": { "get": { "summary": "List backups", "description": "Lists backups in your organization. You can filter results by TiDB Cloud Premium instance ID, backup state, service plan, region, TiDB Cloud Premium instance state, trigger type, or creation time.", "operationId": "BackupService_ListBackups", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListBackupsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbIds", "description": "A list of TiDB Cloud Premium instance IDs. If specified, only backups that belong to these TiDB Cloud Premium instances are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "states", "description": "A list of backup states. If specified, only backups in these states are returned.\n\n - UNKNOWN: The backup state is unknown.\n - PENDING: The backup is pending.\n - RUNNING: The backup is in progress.\n - SUCCEEDED: The backup completed successfully.\n - FAILED: The backup has failed.\n - CANCELLED: The backup is cancelled.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELLED" ] }, "collectionFormat": "multi" }, { "name": "servicePlans", "description": "A list of service plans. If specified, only backups that belong to these service plans are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "Premium" ] }, "collectionFormat": "multi" }, { "name": "regionIds", "description": "A list of region IDs. If specified, only backups in these regions are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "tidbStates", "description": "A list of TiDB Cloud Premium instance states. If specified, only backups that belong to TiDB Cloud Premium instances in these states are returned.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "DELETED" ] }, "collectionFormat": "multi" }, { "name": "triggerTypes", "description": "A list of backup trigger types. If specified, only backups with these trigger types are returned.\n\n - AUTO: The backup is triggered automatically by TiDB Cloud.\n - MANUAL: The backup is triggered manually by a user.", "in": "query", "required": false, "type": "array", "items": { "type": "string", "enum": [ "AUTO", "MANUAL" ] }, "collectionFormat": "multi" }, { "name": "startTime", "description": "The start time of the creation time range. If specified, only backups created after this time are returned.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "endTime", "description": "The end time of the creation time range. If specified, only backups created before this time are returned.", "in": "query", "required": false, "type": "string", "format": "date-time" }, { "name": "pageSize", "description": "The maximum number of backups to return. If not specified, at most 10 backups will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.", "in": "query", "required": false, "type": "integer", "format": "int32", "default": "10" }, { "name": "pageToken", "description": "The pagination token received from a previous [List backups](#tag/Backup/operation/BackupService_ListBackups) 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 backups to skip before returning results. If the value exceeds the total number of backups, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/backups' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/backups/{backupId}": { "delete": { "summary": "Delete a backup", "description": "Deletes a backup by `backupId`.", "operationId": "BackupService_DeleteBackup", "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "backupId", "description": "The ID of the backup to delete.", "in": "path", "required": true, "type": "string" } ], "tags": [ "Backup" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/backups/{backup_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/regions": { "get": { "summary": "List regions", "description": "Lists the regions where you can create a TiDB Cloud Premium instance. You can filter results by cloud provider or service plan.", "operationId": "RegionService_ListRegions", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListRegionsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "cloudProvider", "description": "The cloud provider. If specified, only regions belonging to the specified cloud provider are returned.", "in": "query", "required": false, "type": "string" }, { "name": "servicePlan", "description": "The plan of the service. If specified, only regions that support the specified service plan are returned.", "in": "query", "required": false, "type": "string", "enum": [ "Premium" ] }, { "name": "pageSize", "description": "The maximum number of regions to return. If not specified, at most 10 regions will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.", "in": "query", "required": false, "type": "integer", "format": "int32", "default": "10" }, { "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 regions, the response is `200` with an empty list and no `nextPageToken`.", "in": "query", "required": false, "type": "integer", "format": "int32" } ], "tags": [ "Region" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/regions' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/changefeeds": { "get": { "summary": "List changefeeds", "description": "Lists the changefeeds for a TiDB Cloud Premium instance. Results can be filtered by downstream type and paginated using the page token.", "operationId": "ListChangefeeds", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListChangefeedsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "tidbId", "description": "The ID of the TiDB Cloud Premium instance for which to list changefeeds. You can get the instance ID from [List TiDB Cloud Premium instances](#tag/TiDB-Instance/operation/TidbService_ListTidbs).", "in": "query", "required": true, "type": "string", "x-example": "1234567890123" }, { "name": "downstreamType", "description": "Filters changefeeds by downstream type. If omitted or set to `DOWNSTREAM_TYPE_UNSPECIFIED`, all downstream types are returned.\n\n- `KAFKA`: Apache Kafka.\n- `MYSQL`: MySQL-compatible database.\n- `S3`: Amazon S3 or S3-compatible storage.", "in": "query", "required": false, "type": "string", "enum": [ "DOWNSTREAM_TYPE_UNSPECIFIED", "KAFKA", "MYSQL", "S3" ], "default": "DOWNSTREAM_TYPE_UNSPECIFIED", "x-example": "KAFKA" }, { "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 pagination token received from a previous [List changefeeds](#tag/Changefeed/operation/ListChangefeeds) request. Use this token to retrieve the next page of results.\n\n**Note**: When paginating, all other parameters must match the original request.", "in": "query", "required": false, "type": "string" } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/changefeeds?tidbId={tidb_id}&downstreamType=KAFKA' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] }, "post": { "summary": "Create a changefeed", "description": "Creates a new changefeed for replicating data to a downstream system.\n\nFor S3-compatible storage, Alibaba Cloud OSS is supported through the S3-compatible endpoint. To use Alibaba Cloud OSS, set `downstreamType` to `S3`, set `provider` to `ALIBABA_OSS`, and configure the S3 endpoint with a `s3://{bucket_name}/{prefix}/` URI, a regional custom endpoint such as `https://s3.oss-{region_id}.aliyuncs.com`, and `S3_AUTH_TYPE_AK_SK` authentication.\n\nCurrently, Alibaba Cloud OSS only supports Access Key and Secret Key authentication. IAM Assume Role authentication is not supported.", "operationId": "CreateChangefeed", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2Changefeed" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "description": "The request for creating a changefeed.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1beta2CreateChangefeedRequest" } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl (kafka)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/changefeeds' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"changefeed\": {\n \"tidbId\": \"{tidb_id}\",\n \"name\": \"cf-kafka-demo-001\",\n \"changefeedCapacity\": \"2ccu\",\n \"downstreamType\": \"KAFKA\",\n \"networkInfo\": {\n \"networkType\": \"NETWORK_TYPE_PUBLIC\"\n },\n \"tableConfig\": {\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": false\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"kafka\": {\n \"broker\": {\n \"version\": \"KAFKA_VERSION_3XX\",\n \"brokerEndpoints\": \"broker1:9092,broker2:9092\"\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\": \"kafka-topic\",\n \"replicationFactor\": 1,\n \"partitionNum\": 1\n }\n }\n }\n}'" }, { "label": "curl (mysql)", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"changefeed\": {\n \"tidbId\": \"{tidb_id}\",\n \"name\": \"cf-mysql-demo-001\",\n \"changefeedCapacity\": \"2ccu\",\n \"downstreamType\": \"MYSQL\",\n \"networkInfo\": {\n \"networkType\": \"NETWORK_TYPE_PUBLIC\"\n },\n \"tableConfig\": {\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": false\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"mysql\": {\n \"connection\": {\n \"endpoint\": \"mysql-public.example.com:3306\",\n \"username\": \"mysql_user\",\n \"password\": \"********\"\n }\n }\n }\n}'" }, { "label": "curl (s3)", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"changefeed\": {\n \"tidbId\": \"{tidb_id}\",\n \"name\": \"cf-s3-demo-001\",\n \"changefeedCapacity\": \"2ccu\",\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": false\n },\n \"startPosition\": {\n \"mode\": \"FROM_NOW\"\n },\n \"s3\": {\n \"endpoint\": {\n \"s3Uri\": \"s3://{bucket_name}/{prefix}/\",\n \"authType\": \"S3_AUTH_TYPE_ASSUME_ROLE\",\n \"iamAssumedRoleArn\": \"arn:aws:iam::{account_id}:role/{role_name}\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CSV\",\n \"delimiter\": \",\"\n },\n \"storageFlushConfig\": {\n \"interval\": \"1m\",\n \"fileSize\": 67108864\n }\n }\n }\n}'" }, { "label": "curl (oss)", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/changefeeds' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\n \"changefeed\": {\n \"tidbId\": \"{tidb_id}\",\n \"name\": \"cf-oss-demo-001\",\n \"changefeedCapacity\": \"2ccu\",\n \"downstreamType\": \"S3\",\n \"tableConfig\": {\n \"mode\": \"IGNORE_NOT_SUPPORT_TABLE\",\n \"caseSensitive\": false\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\": \"{oss_access_key}\",\n \"secretKey\": \"{oss_secret_key}\",\n \"customEndpoint\": \"https://s3.oss-{region_id}.aliyuncs.com\",\n \"provider\": \"ALIBABA_OSS\"\n },\n \"dataFormat\": {\n \"protocol\": \"PROTOCOL_CANAL_JSON\"\n }\n }\n }\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": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2Changefeed" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to retrieve. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" }, { "name": "invalidateCache", "description": "Indicates whether to bypass the cache and return the real-time checkpoint information.", "in": "query", "required": false, "type": "boolean", "x-example": true } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] }, "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": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to delete. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request DELETE 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } }, "/changefeeds/{changefeedId}:editDownstreamConfig": { "post": { "summary": "Edit changefeed downstream configuration", "description": "Updates the mutable configuration of an existing changefeed. The changefeed must be in the PAUSED state.", "operationId": "EditChangefeedDownstreamConfig", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2Changefeed" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to update. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" }, { "name": "body", "description": "The request for updating the changefeed downstream configuration.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ChangefeedServiceEditChangefeedDownstreamConfigBody" } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}:editDownstreamConfig' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\"downstreamType\":\"KAFKA\",\"tableConfig\":{\"mode\":\"IGNORE_NOT_SUPPORT_TABLE\",\"caseSensitive\":false}}'" } ] } }, "/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": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to pause. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" }, { "name": "body", "description": "Send an empty JSON object (`{}`).", "in": "body", "required": true, "schema": { "type": "object", "properties": {} } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}:pause' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{}'" } ] } }, "/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": "A successful response.", "schema": { "type": "object", "properties": {} } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to resume. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" }, { "name": "body", "description": "Send an empty JSON object (`{}`).", "in": "body", "required": true, "schema": { "type": "object", "properties": {} } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}:resume' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{}'" } ] } }, "/changefeeds/{changefeedId}:scale": { "post": { "summary": "Scale a changefeed", "description": "Scales a changefeed to a different Changefeed Capacity Unit (CCU). The new capacity takes effect after the operation completes.", "operationId": "ScaleChangefeed", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2Changefeed" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "changefeedId", "description": "The ID of the changefeed to scale. You can get the changefeed ID from [List changefeeds](#tag/Changefeed/operation/ListChangefeeds).", "in": "path", "required": true, "type": "string", "x-example": "67890" }, { "name": "body", "description": "The request for scaling the changefeed.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ChangefeedServiceScaleChangefeedBody" } } ], "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location --request POST 'https://cloud.tidbapi.com/v1beta2/changefeeds/{changefeed_id}:scale' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--data '{\"changefeedCapacity\":\"8ccu\"}'" } ] } }, "/changefeeds:listCCUs": { "get": { "summary": "List changefeed CCU options", "description": "Lists the available Changefeed Capacity Unit (CCU) options that can be selected for a changefeed.", "operationId": "ListChangefeedCapacityUnits", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1beta2ListCCUsResponse" } }, "400": { "description": "A request field is invalid.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "401": { "description": "The API key cannot be authenticated.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "403": { "description": "The API key does not have permission to access the resource.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "429": { "description": "You have exceeded the rate limit.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/rpcStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "Changefeed" ], "x-code-samples": [ { "label": "curl", "lang": "curl", "source": "curl --location 'https://cloud.tidbapi.com/v1beta2/changefeeds:listCCUs' \\\n--digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n--header 'Accept: application/json'" } ] } } }, "definitions": { "BackupTriggerType": { "type": "string", "enum": [ "AUTO", "MANUAL" ], "description": "The trigger type of a backup.\n\n - AUTO: The backup is triggered automatically by TiDB Cloud.\n - MANUAL: The backup is triggered manually by a user." }, "CmekAccessIamPrincipalAliyunCmekPrincipal": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The Alibaba Cloud account ID of the CMEK principal.", "readOnly": true } } }, "CmekAccessIamPrincipalAwsCmekPrincipal": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The AWS account ID of the CMEK principal.", "readOnly": true }, "externalId": { "type": "string", "description": "The AWS STS AssumeRole `ExternalId` that must be pinned in the KMS\nkey policy's `Condition` block when granting access to this principal.", "readOnly": true } } }, "ConnectionReachabilityDetail": { "type": "object", "properties": { "serviceActive": { "type": "boolean", "description": "Indicates whether the service is active.", "readOnly": true }, "endpointActive": { "type": "boolean", "description": "Indicates whether the endpoint is active.", "readOnly": true }, "dnsReachable": { "type": "boolean", "description": "Indicates whether the DNS is reachable.", "readOnly": true }, "message": { "type": "string", "description": "A human-readable message that describes the reachability status.", "readOnly": true } } }, "CustomerManagedEncryptionKeyAliyunKms": { "type": "object", "properties": { "kmsKeyArn": { "type": "string", "description": "The Alibaba Cloud KMS key ID used for encryption. For example, `acs:kms:ap-southeast-1:5841052134823325:key/key-sgp68887a54phjt9703ut`." } }, "required": [ "kmsKeyArn" ] }, "CustomerManagedEncryptionKeyAwsKms": { "type": "object", "properties": { "kmsKeyArn": { "type": "string", "description": "The Amazon Resource Name (ARN) of the AWS KMS key used for encryption." } }, "required": [ "kmsKeyArn" ] }, "EndpointConnectionType": { "type": "string", "enum": [ "PUBLIC", "PRIVATE_ENDPOINT", "VPC_PEERING" ] }, "RegionCloudProvider": { "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." }, "TidbDualLayerDataEncryption": { "type": "object", "properties": { "noEncryption": { "type": "object", "properties": {}, "description": "Disables dual-layer data encryption. The TiDB Cloud Premium instance uses the default encryption provided by the cloud provider." }, "defaultKey": { "type": "object", "properties": {}, "description": "Enables dual-layer data encryption using the TiDB Cloud default key." }, "cmek": { "description": "Enables dual-layer data encryption using a customer-managed encryption key (CMEK).\nConfigure the key according to the cloud provider:\n- AWS: set `awsKms` and `awsPrincipal`.\n- Alibaba Cloud: set `aliyunKms` and `aliyunPrincipal`.", "allOf": [ { "$ref": "#/definitions/v1beta2CustomerManagedEncryptionKey" } ] } }, "description": "The dual-layer data encryption configuration for a TiDB Cloud Premium instance. Specify exactly one of the following options: `noEncryption`, `defaultKey`, or `cmek`." }, "TidbEndpoint": { "type": "object", "properties": { "host": { "type": "string", "description": "The hostname of the endpoint.\n\nWhen `connectionType` is `\"PRIVATE_ENDPOINT\"`, the behavior of the `host` field varies by cloud provider:\n- For AWS, this field is available after the Private Link service is ready.\n- For Google Cloud and Azure, this field is available after you create a private endpoint connection.", "readOnly": true }, "port": { "type": "integer", "format": "int32", "description": "The port number of the endpoint.", "readOnly": true }, "connectionType": { "description": "The connection type of the endpoint.\n\n- `PUBLIC`: a public endpoint. For more information, see [Network](https://docs.pingcap.com/tidbcloud/connect-to-tidb-instance/#network).\n\n- `PRIVATE_ENDPOINT`: a private endpoint. For more information, see [Network](https://docs.pingcap.com/tidbcloud/connect-to-tidb-instance/#network).\n\n- `VPC_PEERING`: a VPC peering endpoint (not yet supported, planned for a future release).", "readOnly": true, "allOf": [ { "$ref": "#/definitions/EndpointConnectionType" } ] }, "connectionReachability": { "description": "The reachability status of the endpoint connection.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta2ConnectionReachability" } ] } } }, "TidbHighAvailabilityType": { "type": "string", "enum": [ "REGIONAL", "ZONAL" ], "description": "The high availability configuration for the TiDB Cloud Premium instance.\n\n - REGIONAL: High availability across multiple availability zones within a region.\n - ZONAL: High availability within a single availability zone." }, "TidbServiceResetRootPasswordBody": { "type": "object", "properties": { "rootPassword": { "type": "string", "example": "my-shining-password", "description": "The new root password.\n\nThis field supports two input formats:\n- Plaintext password (legacy behavior)\n- RSA-OAEP-SHA256 encrypted payload prefixed with `rsa_oaep_sha256:`\n\nIf the marker prefix is present, the server parses and decrypts the encrypted payload.\nAny parse/decrypt failure returns an explicit parameter error without plaintext fallback.\nIf the marker prefix is absent, the value is treated as plaintext for backward compatibility.\n\nFor plaintext input, the password must be between 8 and 64 characters long.", "pattern": "^(rsa_oaep_sha256:.+|.{8,64})$" } }, "required": [ "rootPassword" ] }, "nextgenv1beta2Tidb": { "type": "object", "properties": { "name": { "type": "string", "description": "The unique identifier for the TiDB Cloud Premium instance, which is generated by the API and follows the format `tidbs/{tidbId}`.", "readOnly": true }, "tidbId": { "type": "string", "description": "The ID of the TiDB Cloud Premium instance.", "readOnly": true }, "displayName": { "type": "string", "example": "foo-bar", "description": "The user-defined name of the TiDB Cloud Premium instance.", "maxLength": 64, "minLength": 4, "pattern": "^[A-Za-z0-9][-A-Za-z0-9]{2,62}[A-Za-z0-9]$" }, "regionId": { "type": "string", "description": "The unique identifier of the region where the TiDB Cloud Premium instance is deployed, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`." }, "cloudProvider": { "description": "The cloud provider where the TiDB Cloud Premium instance is deployed.\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/RegionCloudProvider" } ] }, "regionDisplayName": { "type": "string", "description": "The display name of the region where the TiDB Cloud Premium instance is deployed. For example, `Oregon (us-west-2)`.", "readOnly": true }, "state": { "description": "The current state of the TiDB Cloud Premium instance.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1ClusterState" } ] }, "rootPassword": { "type": "string", "example": "my-shining-password", "description": "The root password of the TiDB Cloud Premium instance.\n\nThis field supports two input formats:\n- Plaintext password (legacy behavior)\n- RSA-OAEP-SHA256 encrypted payload prefixed with `rsa_oaep_sha256:`\n\nIf the marker prefix is present, the server parses and decrypts the encrypted payload.\nAny parse/decrypt failure returns an explicit parameter error without plaintext fallback.\nIf the marker prefix is absent, the value is treated as plaintext for backward compatibility.\n\nFor plaintext input, the password must be between 8 and 64 characters long and can contain letters,\nnumbers, and special characters.", "pattern": "^(rsa_oaep_sha256:.+|.{8,64})$" }, "minRcu": { "type": "string", "format": "int64", "description": "The minimum number of Request Capacity Units (RCUs) for the TiDB Cloud Premium instance.\n\nThis field is read-only and is automatically calculated as `max(5000, maxRcu / 4)`.", "readOnly": true }, "maxRcu": { "type": "string", "format": "int64", "description": "The maximum number of Request Capacity Units (RCUs) for the TiDB Cloud Premium instance." }, "servicePlan": { "description": "The plan of the service.\n\n- `Premium`: [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-premium)", "allOf": [ { "$ref": "#/definitions/v1beta1ServicePlan" } ] }, "highAvailabilityType": { "description": "The high availability configuration for the TiDB Cloud Premium instance.\n- `REGIONAL`: high availability across multiple availability zones within a region. This is the only supported mode for TiDB Cloud Premium instances. For more information, see [Regional high availability architecture](https://docs.pingcap.com/tidbcloud/serverless-high-availability/#regional-high-availability-architecture).\n- `ZONAL`: high availability within a single availability zone. This mode is not supported for TiDB Cloud Premium instances and is reserved for other service plans. For more information, see [Zonal high availability architecture](https://docs.pingcap.com/tidbcloud/serverless-high-availability/#zonal-high-availability-architecture).", "readOnly": true, "allOf": [ { "$ref": "#/definitions/TidbHighAvailabilityType" } ] }, "annotations": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The annotations for the TiDB Cloud Premium instance. The following lists some predefined annotations:\n- `tidb.cloud/has-set-password`: indicates whether the TiDB Cloud Premium instance has a root password set.\n- `tidb.cloud/available-features`: lists available features of the TiDB Cloud Premium instance." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The labels for the TiDB Cloud Premium instance.\n- `tidb.cloud/organization`: the ID of the organization where the TiDB Cloud Premium instance belongs.\n- `tidb.cloud/project`: the ID of the project where the TiDB Cloud Premium instance belongs." }, "creator": { "type": "string", "description": "The email address or public API key of the user who created the TiDB Cloud Premium instance.", "readOnly": true }, "createTime": { "type": "string", "format": "date-time", "description": "The timestamp when the TiDB Cloud Premium instance was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "updateTime": { "type": "string", "format": "date-time", "description": "The timestamp when the TiDB Cloud Premium instance was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "endpoints": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/TidbEndpoint" }, "description": "The connection endpoints for accessing the TiDB Cloud Premium instance.", "readOnly": true }, "dualLayerDataEncryption": { "description": "The dual-layer data encryption configuration for the TiDB Cloud Premium instance.", "allOf": [ { "$ref": "#/definitions/TidbDualLayerDataEncryption" } ] }, "tidbVersion": { "type": "string", "description": "The version of the TiDB instance.", "readOnly": true }, "tags": { "type": "array", "items": { "type": "string" } }, "capacityUpdateTime": { "type": "string", "format": "date-time", "description": "The timestamp when the capacity of the TiDB Cloud Premium instance was last updated, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true } }, "required": [ "displayName", "regionId", "maxRcu", "servicePlan" ] }, "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 }" }, "rpcStatus": { "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": { "type": "object", "$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)." }, "v1beta1ClusterState": { "type": "string", "enum": [ "CREATING", "DELETING", "ACTIVE", "RESTORING", "MAINTENANCE", "DELETED", "INACTIVE", "UPGRADING", "IMPORTING", "MODIFYING", "PAUSING", "PAUSED", "RESUMING" ], "description": "The possible states of a TiDB Cloud Premium instance.\n\n - CREATING: The TiDB Cloud Premium instance is being created.\n - DELETING: The TiDB Cloud Premium instance is being deleted.\n - ACTIVE: The TiDB Cloud Premium instance is active for use.\n - RESTORING: Data for the TiDB Cloud Premium instance is being restored.\n - MAINTENANCE: The TiDB Cloud Premium instance is under maintenance.\n - DELETED: The TiDB Cloud Premium instance has been deleted.\n - INACTIVE: The TiDB Cloud Premium instance is not active, but is 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." }, "v1beta1Region": { "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/RegionCloudProvider" } ] }, "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`.", "title": "Deprecated", "readOnly": true }, "servicePlans": { "type": "array", "example": [ "Premium" ], "items": { "$ref": "#/definitions/v1beta1ServicePlan" }, "description": "The service plans available in this region.", "title": "ServicePlan", "readOnly": true }, "supportedServicePlans": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1beta1ServicePlanInfo" }, "readOnly": true } }, "description": "A representation of a region for deploying TiDB Cloud Premium instances." }, "v1beta1ServicePlan": { "type": "string", "enum": [ "Premium" ] }, "v1beta1ServicePlanInfo": { "type": "object", "properties": { "servicePlan": { "$ref": "#/definitions/v1beta1ServicePlan" }, "displayName": { "type": "string" } } }, "v1beta2Backup": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the backup.", "readOnly": true }, "tidbId": { "type": "string", "description": "The ID of the TiDB Cloud Premium instance to which the backup belongs.", "readOnly": true }, "organizationId": { "type": "string", "description": "The ID of the organization to which the backup belongs.", "readOnly": true }, "servicePlan": { "example": "Premium", "description": "The service plan of the backup. The possible value is `Premium`.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta1ServicePlan" } ] }, "displayName": { "type": "string", "description": "The name of the backup.", "readOnly": true }, "description": { "type": "string", "description": "The description of the backup." }, "createTime": { "type": "string", "format": "date-time", "description": "The timestamp when the backup was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "sizeBytes": { "type": "string", "format": "int64", "description": "The size of the backup in bytes.", "readOnly": true }, "state": { "description": "The current state of the backup.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta2BackupState" } ] }, "type": { "description": "The type of the backup.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta2BackupType" } ] }, "triggerType": { "description": "The trigger type of the backup.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/BackupTriggerType" } ] }, "expirationTime": { "type": "string", "format": "date-time", "description": "The timestamp when the backup expires, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true }, "backupTs": { "type": "string", "description": "The backup timestamp.", "readOnly": true }, "regionId": { "type": "string", "description": "The ID of the region where the backup is stored.", "readOnly": true }, "customerManaged": { "type": "boolean", "description": "Whether the source TiDB Cloud Premium instance used a customer-managed key at backup time. Interpret this field together with `encryptionKeyId`:\n\n- `encryptionKeyId` is `\"0\"`: The backup was not encrypted.\n- `encryptionKeyId` is not `\"0\"` and `customerManaged` is `false`: The backup used SMEK.\n- `encryptionKeyId` is not `\"0\"` and `customerManaged` is `true`: The backup used CMEK.", "readOnly": true }, "encryptionKeyId": { "type": "string", "description": "The encryption key ID of the source TiDB Cloud Premium instance at backup time. `\"0\"` means no encryption key was used.", "readOnly": true } } }, "v1beta2BackupState": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELLED" ], "description": "The state of a backup.\n\n - UNKNOWN: The backup state is unknown.\n - PENDING: The backup is pending.\n - RUNNING: The backup is in progress.\n - SUCCEEDED: The backup completed successfully.\n - FAILED: The backup has failed.\n - CANCELLED: The backup is cancelled." }, "v1beta2BackupStorageAuth": { "type": "object", "properties": { "accessKeyId": { "type": "string", "description": "The access key ID used to access the backup storage." }, "accessKeySecret": { "type": "string", "description": "The access key secret used to access the backup storage." } }, "required": [ "accessKeyId", "accessKeySecret" ] }, "v1beta2BackupType": { "type": "string", "enum": [ "SNAPSHOT" ], "description": "The type of a backup.\n\n - SNAPSHOT: A full snapshot backup." }, "v1beta2CaCertificateDownloadUrl": { "type": "object", "properties": { "uri": { "type": "string", "description": "The download URL for the CA certificate of the TiDB Cloud Premium instance.", "readOnly": true } } }, "v1beta2ClassicBackupStorage": { "type": "object", "properties": { "cloudProvider": { "example": "aws", "description": "The cloud provider where the backup object storage is located.\n\n**Note**: Currently, only `\"aws\"` and `\"alicloud\"` are supported.", "allOf": [ { "$ref": "#/definitions/RegionCloudProvider" } ] }, "regionId": { "type": "string", "description": "The region where the backup object storage is located, in the format of `{cloud_provider}-{region_code}`. For example, `alicloud-cn-shanghai`.\n\nThis field is required when `cloud_provider` is `\"alicloud\"`." }, "bucketUri": { "type": "string", "example": "s3://my-backup-bucket/tidb-backups/", "description": "The URI of the backup bucket.\n\n- For Amazon S3, use the format `s3://{bucket_name}/{path}`. For example, `s3://my-backup-bucket/tidb-backups/`.\n\n- For Alibaba Cloud OSS, use the format `oss://{bucket_name}/{path}`. For example, `oss://my-backup-bucket/tidb-backups/`." }, "auth": { "description": "The authentication credentials for accessing the backup storage.", "allOf": [ { "$ref": "#/definitions/v1beta2BackupStorageAuth" } ] } }, "description": "The storage configuration for a classic backup.", "required": [ "cloudProvider", "bucketUri", "auth" ] }, "v1beta2CloudProviderInfo": { "type": "object", "properties": { "tidbId": { "type": "string", "description": "The ID of the TiDB Cloud Premium instance." }, "cloudProvider": { "description": "The cloud provider where the TiDB Cloud Premium instance is deployed.\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/RegionCloudProvider" } ] }, "tidbCloudAccountId": { "type": "string", "description": "The TiDB Cloud account ID for the underlying cloud infrastructure of the TiDB Cloud Premium instance.", "readOnly": true }, "tidbCloudAccountExternalId": { "type": "string", "description": "The external ID of the TiDB Cloud account, which is used for assuming Identity and Access Management (IAM) roles for cross-account access.", "readOnly": true }, "nodeRole": { "type": "string", "description": "The node role or identity used to grant storage access.\nFor Azure, this is the kubelet identity object ID.", "readOnly": true } }, "required": [ "tidbId" ] }, "v1beta2ConnectionReachability": { "type": "object", "properties": { "reachable": { "type": "boolean", "description": "Indicates whether the endpoint is reachable.", "readOnly": true }, "detail": { "description": "The detailed reachability status of the endpoint connection.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/ConnectionReachabilityDetail" } ] } } }, "v1beta2CustomerManagedEncryptionKey": { "type": "object", "properties": { "name": { "type": "string", "description": "The unique name of the CMEK, in the format of `cmeks/{cmek_id}`.", "readOnly": true }, "customerManagedEncryptionKeyId": { "type": "string", "description": "The ID of the CMEK.", "readOnly": true }, "regionId": { "type": "string", "description": "The region where the CMEK is located, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`." }, "cloudProvider": { "description": "The cloud provider where the CMEK is located.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud (not yet supported, planned for a future release)\n\n- `\"azure\"`: Microsoft Azure (not yet supported, planned for a future release)\n\n- `\"alicloud\"`: Alibaba Cloud", "readOnly": true, "allOf": [ { "$ref": "#/definitions/RegionCloudProvider" } ] }, "servicePlan": { "$ref": "#/definitions/v1beta1ServicePlan" }, "awsKms": { "description": "The configuration for AWS KMS.", "allOf": [ { "$ref": "#/definitions/CustomerManagedEncryptionKeyAwsKms" } ] }, "aliyunKms": { "description": "The configuration for Alibaba Cloud KMS.", "allOf": [ { "$ref": "#/definitions/CustomerManagedEncryptionKeyAliyunKms" } ] }, "awsPrincipal": { "description": "AWS IAM principal.", "allOf": [ { "$ref": "#/definitions/CmekAccessIamPrincipalAwsCmekPrincipal" } ] }, "aliyunPrincipal": { "description": "Alibaba Cloud RAM principal.", "allOf": [ { "$ref": "#/definitions/CmekAccessIamPrincipalAliyunCmekPrincipal" } ] }, "createTime": { "type": "string", "format": "date-time", "description": "The timestamp when the CMEK was created, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true } }, "required": [ "regionId", "servicePlan" ] }, "v1beta2GetRestoreStatusResponse": { "type": "object", "properties": { "state": { "description": "The current state of the restore operation.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/v1beta2RestoreState" } ] }, "message": { "type": "string", "description": "The detailed error message if the restore operation fails.", "readOnly": true }, "progress": { "type": "integer", "format": "int32", "description": "The restore progress percentage, from `0` to `100`.", "readOnly": true } } }, "v1beta2ListBackupsResponse": { "type": "object", "properties": { "backups": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1beta2Backup" }, "description": "A list of backups that match the query." }, "totalSize": { "type": "integer", "format": "int32", "description": "The total number of backups 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." } } }, "v1beta2ListRegionsResponse": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1beta1Region" }, "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." } } }, "v1beta2ListTidbBackupsResponse": { "type": "object", "properties": { "backups": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1beta2Backup" }, "description": "A list of backups that match the query." }, "totalSize": { "type": "integer", "format": "int32", "description": "The total number of backups 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." } } }, "v1beta2ListTidbsResponse": { "type": "object", "properties": { "tidbs": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/nextgenv1beta2Tidb" }, "description": "A list of TiDB Cloud Premium instances that match the query." }, "totalSize": { "type": "integer", "format": "int32", "description": "The total number of TiDB Cloud Premium instances 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." } } }, "v1beta2ResetRootPasswordResponse": { "type": "object" }, "v1beta2RestoreMode": { "type": "string", "enum": [ "SNAPSHOT", "PITR", "DEDICATED_SNAPSHOT", "CLASSIC_SNAPSHOT" ], "description": "The mode used to restore a TiDB Cloud Premium instance.\n\n - SNAPSHOT: Restores from native snapshot backup data of a TiDB Cloud Premium instance.\n - PITR: Restores from native point-in-time recovery (PITR) backup data of a TiDB Cloud Premium instance.\n - DEDICATED_SNAPSHOT: Restores from snapshot backup data of a TiDB Cloud Dedicated cluster.\n - CLASSIC_SNAPSHOT: Restores from snapshot backup data stored in object storage of a classic TiDB." }, "v1beta2RestoreState": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "CANCELLED" ], "description": "The current state of the restore operation.\n\n - UNKNOWN: The state of the restore operation is unknown.\n - PENDING: The restore operation is pending.\n - RUNNING: The restore operation is in progress.\n - SUCCEEDED: The restore operation completed successfully.\n - FAILED: The restore operation has failed.\n - CANCELLED: The restore operation is cancelled." }, "v1beta2RestoreTidbRequest": { "type": "object", "properties": { "tidb": { "description": "The configuration of the TiDB Cloud Premium instance to create.\n\n**Note**: Currently, only TiDB Cloud Premium instances with `servicePlan` set to `Premium` are supported.", "allOf": [ { "$ref": "#/definitions/nextgenv1beta2Tidb" } ] }, "sourceTidbId": { "type": "string", "description": "The ID of the source TiDB Cloud Premium instance containing the backup data." }, "restoreMode": { "$ref": "#/definitions/v1beta2RestoreMode" }, "backupId": { "type": "string", "description": "The ID of the backup to restore from.\n\nThis field is required when `restoreMode` is `\"SNAPSHOT\"` or `\"DEDICATED_SNAPSHOT\"`." }, "pointInTime": { "type": "string", "format": "date-time", "description": "The point in time to restore data to, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.\n\nThis field is required when `restoreMode` is `\"PITR\"`." }, "classicBackupStorage": { "description": "The classic backup storage configuration.\n\nThis field is required when `restoreMode` is `\"CLASSIC_SNAPSHOT\"`.", "allOf": [ { "$ref": "#/definitions/v1beta2ClassicBackupStorage" } ] }, "validateOnly": { "type": "boolean", "description": "If set to `true`, the request is validated but not executed. Defaults to `false`." } }, "required": [ "tidb", "restoreMode" ] }, "v1beta2RestoreTidbResponse": { "type": "object", "properties": { "tidb": { "description": "The restored TiDB Cloud Premium instance.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/nextgenv1beta2Tidb" } ] } } }, "AvroConfigBigintUnsignedHandlingMode": { "type": "string", "enum": [ "BIGINT_UNSIGNED_HANDLING_MODE_LONG", "BIGINT_UNSIGNED_HANDLING_MODE_STRING" ], "default": "BIGINT_UNSIGNED_HANDLING_MODE_LONG", "description": "BigintUnsignedHandlingMode defines how BIGINT UNSIGNED values are handled.\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_PRECISE", "DECIMAL_HANDLING_MODE_STRING" ], "default": "DECIMAL_HANDLING_MODE_PRECISE", "description": "DecimalHandlingMode defines how decimal values are serialized.\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", "example": true, "description": "Indicates whether to enable HTTP basic authentication for Schema Registry." }, "basicAuthUsername": { "type": "string", "example": "schema_user", "description": "The basic authentication username for Schema Registry." }, "basicAuthPassword": { "type": "string", "example": "********", "description": "The basic authentication password for Schema Registry." } }, "description": "The Schema Registry connection configuration." }, "ChangefeedServiceEditChangefeedDownstreamConfigBody": { "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/v1beta2TableConfig" } ] }, "downstreamType": { "example": "KAFKA", "description": "The downstream type for a changefeed. Must match the existing downstream type (cannot be changed).", "allOf": [ { "$ref": "#/definitions/v1beta2DownstreamType" } ] }, "kafka": { "description": "The updated Kafka downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfig" } ] }, "mysql": { "description": "The updated MySQL downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2MySQLDownstreamConfig" } ] }, "s3": { "description": "The updated S3 downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2S3DownstreamConfig" } ] } }, "description": "The request for updating a changefeed downstream configuration.", "required": [ "downstreamType" ] }, "ChangefeedServiceScaleChangefeedBody": { "type": "object", "properties": { "changefeedCapacity": { "type": "string", "example": "8ccu", "description": "The name of the target changefeed capacity option, such as `\"8ccu\"`. Use the exact `name` value returned by [List changefeed CCU options](#tag/Changefeed/operation/ListChangefeedCapacityUnits)." } }, "description": "The request for scaling a changefeed.", "required": [ "changefeedCapacity" ] }, "ChangefeedState": { "type": "string", "enum": [ "STATE_UNSPECIFIED", "RUNNING", "FAILED", "ERROR", "CREATING", "PAUSING", "PAUSED", "DELETING", "DELETED", "EDITING", "WARNING", "SCALING", "RESUMING" ], "default": "STATE_UNSPECIFIED", "description": "State defines the possible states of a changefeed.\n\n - STATE_UNSPECIFIED: Default value. Should not be used.\n - RUNNING: Changefeed is actively replicating data.\n - FAILED: Changefeed encountered a fatal error and stopped.\n - ERROR: Changefeed encountered an error but may recover.\n - CREATING: Changefeed is being created.\n - PAUSING: Changefeed is in the process of pausing.\n - PAUSED: Changefeed is paused.\n - DELETING: Changefeed is being deleted.\n - DELETED: Changefeed has been deleted.\n - EDITING: Changefeed configuration is being updated.\n - WARNING: Changefeed is running but has warnings.\n - SCALING: Changefeed is being scaled.\n - RESUMING: Changefeed is being resumed." }, "DataFormatAvroConfig": { "type": "object", "properties": { "decimalHandlingMode": { "example": "DECIMAL_HANDLING_MODE_PRECISE", "description": "The decimal serialization mode. The default value is `DECIMAL_HANDLING_MODE_PRECISE`.\n\n- `\"DECIMAL_HANDLING_MODE_PRECISE\"`: Use precise decimal representation.\n\n- `\"DECIMAL_HANDLING_MODE_STRING\"`: Use string representation.", "allOf": [ { "$ref": "#/definitions/AvroConfigDecimalHandlingMode" } ] }, "bigintUnsignedHandlingMode": { "example": "BIGINT_UNSIGNED_HANDLING_MODE_STRING", "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\n- `\"BIGINT_UNSIGNED_HANDLING_MODE_STRING\"`: Use string representation (safe for all values).", "allOf": [ { "$ref": "#/definitions/AvroConfigBigintUnsignedHandlingMode" } ] }, "schemaRegistry": { "description": "The Schema Registry connection configuration.", "allOf": [ { "$ref": "#/definitions/AvroConfigSchemaRegistry" } ] } }, "description": "The Avro-specific data format configuration." }, "DataFormatDebeziumConfig": { "type": "object", "properties": { "outputOldValue": { "type": "boolean", "example": true, "description": "Indicates whether to output the old value before the change." }, "disableSchema": { "type": "boolean", "example": false, "description": "Indicates whether to disable the schema in Debezium messages." } }, "description": "The Debezium-specific data format configuration." }, "EndpointProvider": { "type": "string", "enum": [ "PROVIDER_UNSPECIFIED", "AWS", "ALIBABA_OSS" ], "default": "PROVIDER_UNSPECIFIED", "description": "Provider defines the S3-compatible object storage provider.\n\n - PROVIDER_UNSPECIFIED: Default value. Uses AWS S3 behavior.\n - AWS: Amazon S3.\n - ALIBABA_OSS: Alibaba Cloud OSS through its S3-compatible endpoint." }, "EndpointS3AuthType": { "type": "string", "enum": [ "S3_AUTH_TYPE_AK_SK", "S3_AUTH_TYPE_ASSUME_ROLE" ], "description": "S3AuthType defines the supported S3 authentication types.\n\n - S3_AUTH_TYPE_AK_SK: Access Key / Secret Key authentication.\n - S3_AUTH_TYPE_ASSUME_ROLE: IAM Assume Role authentication." }, "KafkaDownstreamConfigBroker": { "type": "object", "properties": { "version": { "example": "KAFKA_VERSION_3XX", "description": "The Kafka broker version.\n\n- `\"KAFKA_VERSION_UNSPECIFIED\"`: Default value. Must not be used.\n\n- `\"KAFKA_VERSION_1XX\"`: Kafka 1.x\n\n- `\"KAFKA_VERSION_2XX\"`: Kafka 2.x\n\n- `\"KAFKA_VERSION_3XX\"`: Kafka 3.x", "allOf": [ { "$ref": "#/definitions/KafkaDownstreamConfigKafkaVersion" } ] }, "brokerEndpoints": { "type": "string", "example": "broker1:9092,broker2:9092,broker3:9092", "description": "The comma-separated list of Kafka broker addresses. Required for PUBLIC and VPC_PEERING network types. For PRIVATE_LINK, this field can be omitted; the server assembles broker endpoints from `networkInfo.sinkEndpointId` and `networkInfo.ports`." }, "useTls": { "type": "boolean", "example": true, "description": "Indicates whether to use TLS for the Kafka connection. The default value is false." }, "insecureSkipVerify": { "type": "boolean", "example": false, "description": "Indicates whether to skip TLS certificate verification. The default value is false. Only enable this field for testing with self-signed certificates." }, "compression": { "example": "LZ4", "description": "The Kafka message compression type. The default value is `NONE`.\n\n- `\"NONE\"`: No compression.\n\n- `\"GZIP\"`: GZIP compression.\n\n- `\"SNAPPY\"`: Snappy compression.\n\n- `\"LZ4\"`: LZ4 compression.\n\n- `\"ZSTD\"`: ZSTD compression.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfigCompressionType" } ] }, "kafkaClientId": { "type": "string", "example": "my-changefeed-client", "description": "The optional Kafka client ID. When left empty, a system default is used." } }, "description": "The Kafka broker connection configuration.", "required": [ "version" ] }, "KafkaDownstreamConfigColumnSelector": { "type": "object", "properties": { "matcher": { "type": "array", "example": [ "mydb.orders", "mydb.user_*" ], "items": { "type": "string" }, "description": "The table name patterns to match for column selection." }, "columns": { "type": "array", "example": [ "id", "name", "status" ], "items": { "type": "string" }, "description": "The column names to include for the matched tables." } }, "description": "The column filtering configuration for specific tables." }, "KafkaDownstreamConfigKafkaVersion": { "type": "string", "enum": [ "KAFKA_VERSION_UNSPECIFIED", "KAFKA_VERSION_1XX", "KAFKA_VERSION_2XX", "KAFKA_VERSION_3XX" ], "default": "KAFKA_VERSION_UNSPECIFIED", "description": "KafkaVersion defines supported Kafka broker versions.\n\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", "description": "The message dispatch type to topics. This field is required, and the API does not provide a default dispatch type. Specify one of the following values.\n\n- `\"DISPATCH_TYPE_ONE_TOPIC\"`: All messages go to a single topic.\n\n- `\"DISPATCH_TYPE_BY_TABLE\"`: Each table gets its own topic.\n\n- `\"DISPATCH_TYPE_BY_DATABASE\"`: Each database gets its own topic.", "allOf": [ { "$ref": "#/definitions/TopicPartitionConfigDispatchType" } ] }, "defaultTopic": { "type": "string", "example": "cdc-events", "description": "The default topic for dispatching all messages when dispatchType is DISPATCH_TYPE_ONE_TOPIC." }, "topicPrefix": { "type": "string", "example": "cdc-", "description": "The topic name prefix for dispatch types that create per-table or per-database topics." }, "separator": { "type": "string", "example": ".", "description": "The separator between the prefix and the table or database name." }, "topicSuffix": { "type": "string", "example": "-v1", "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": [ "BASE64", "HEX" ], "default": "BASE64", "description": "BinaryEncodingMethod defines how binary values are encoded.\n\n - BASE64: Base64 encoding.\n - HEX: Hexadecimal encoding." }, "S3DataFormatDateSeparator": { "type": "string", "enum": [ "NONE", "YEAR", "MONTH", "DAY" ], "default": "NONE", "description": "DateSeparator defines the date separator options for 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_ONE_TOPIC", "DISPATCH_TYPE_BY_TABLE", "DISPATCH_TYPE_BY_DATABASE" ], "description": "DispatchType defines how messages are dispatched 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": [ "TABLE", "INDEX_VALUE", "TIMESTAMP", "COLUMNS" ], "description": "PartitionDispatcher defines the partition dispatch strategies.\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", "description": "The partition dispatch strategy. This field is required, and the API does not provide a default strategy. Specify one of the following values.\n\n- `\"TABLE\"`: Dispatch by table name.\n\n- `\"INDEX_VALUE\"`: Dispatch by index value.\n\n- `\"TIMESTAMP\"`: Dispatch by timestamp.\n\n- `\"COLUMNS\"`: Dispatch by column values.", "allOf": [ { "$ref": "#/definitions/TopicPartitionConfigPartitionDispatcher" } ] }, "matcher": { "type": "array", "example": [ "mydb.orders" ], "items": { "type": "string" }, "description": "The table name patterns to match for the dispatcher." }, "indexName": { "type": "string", "example": "primary", "description": "The index name for the INDEX_VALUE partition dispatcher." }, "columns": { "type": "array", "example": [ "user_id", "order_id" ], "items": { "type": "string" }, "description": "The column names for the COLUMNS partition dispatcher." } }, "description": "The custom partition dispatcher configuration.", "required": [ "partitionType", "matcher" ] }, "v1beta2Changefeed": { "type": "object", "properties": { "id": { "type": "string", "example": "67890", "description": "The system-generated unique identifier of the changefeed.", "readOnly": true }, "tidbId": { "type": "string", "example": "1234567890123", "description": "The ID of the source TiDB instance." }, "name": { "type": "string", "example": "my-kafka-changefeed", "description": "The user-defined name for the changefeed. Must be unique within the TiDB instance." }, "networkInfo": { "description": "The network configuration for connecting to the downstream. Required for Kafka and MySQL downstream types.", "allOf": [ { "$ref": "#/definitions/v1beta2NetworkInfo" } ] }, "state": { "example": "RUNNING", "description": "The current state of the changefeed.", "readOnly": true, "allOf": [ { "$ref": "#/definitions/ChangefeedState" } ] }, "createTime": { "type": "string", "format": "date-time", "example": "2026-06-08T10:30:00Z", "description": "The creation time of the changefeed.", "readOnly": true }, "checkpointTso": { "type": "string", "format": "uint64", "example": "452348901234567890", "description": "The checkpoint TSO of the changefeed, representing the last successfully replicated timestamp.", "readOnly": true }, "checkpointTs": { "type": "string", "format": "date-time", "example": "2026-06-08T10:35:00Z", "description": "The human-readable checkpoint timestamp of the changefeed.", "readOnly": true }, "changefeedCapacity": { "type": "string", "example": "4ccu", "description": "The name of the changefeed capacity option for the changefeed, such as `\"4ccu\"`. Use the exact `name` value returned by [List changefeed CCU options](#tag/Changefeed/operation/ListChangefeedCapacityUnits)." }, "downstreamType": { "example": "KAFKA", "description": "The downstream type for a changefeed. When a downstream type is specified, the corresponding configuration field (`kafka`, `mysql`, or `s3`) is required. Cannot be changed after creation.\n\n- `\"KAFKA\"`: Apache Kafka\n\n- `\"MYSQL\"`: MySQL-compatible database\n\n- `\"S3\"`: Amazon S3 or S3-compatible storage", "allOf": [ { "$ref": "#/definitions/v1beta2DownstreamType" } ] }, "tableConfig": { "description": "The table filtering and event filter configuration. This field is editable only when the changefeed is in PAUSED state.", "allOf": [ { "$ref": "#/definitions/v1beta2TableConfig" } ] }, "startPosition": { "description": "The start position configuration. This field can only be set during creation.", "allOf": [ { "$ref": "#/definitions/v1beta2StartPosition" } ] }, "kafka": { "description": "The Kafka downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfig" } ] }, "mysql": { "description": "The MySQL downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2MySQLDownstreamConfig" } ] }, "s3": { "description": "The S3 downstream configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2S3DownstreamConfig" } ] }, "error": { "type": "string", "example": "kafka: broker not available", "description": "The error message when the changefeed is in the FAILED or ERROR state. This field is empty otherwise.", "readOnly": true } }, "description": "The changefeed configuration.", "required": [ "tidbId", "name", "changefeedCapacity", "downstreamType", "tableConfig", "startPosition" ] }, "v1beta2ChangefeedCCU": { "type": "object", "properties": { "name": { "type": "string", "example": "4ccu", "description": "The identifier of the CCU option.", "readOnly": true }, "displayName": { "type": "string", "example": "4 CCU - Small", "description": "The human-readable display name of the CCU option.", "readOnly": true }, "ccuNum": { "type": "integer", "format": "int64", "example": 4, "description": "The number of CCUs (Changefeed Capacity Units).", "readOnly": true }, "rpsLimit": { "type": "integer", "format": "int64", "example": 5000, "description": "The maximum rows per second for the CCU option. This value is for reference only and may vary by workload.", "readOnly": true } }, "description": "The changefeed CCU option." }, "v1beta2Connection": { "type": "object", "properties": { "endpoint": { "type": "string", "example": "mysql.example.com:3306", "description": "The MySQL endpoint address in the `host:port` format. Required for PUBLIC and VPC_PEERING networks. For PRIVATE_LINK, this field can be omitted; the server assembles the endpoint from `networkInfo.sinkEndpointId` and `networkInfo.ports`." }, "username": { "type": "string", "example": "cdc_user", "description": "The MySQL username for authentication." }, "password": { "type": "string", "example": "********", "description": "The MySQL password for authentication. This field is input-only and not returned in responses." } }, "description": "The MySQL connection configuration.", "required": [ "username" ] }, "v1beta2CreateChangefeedRequest": { "type": "object", "properties": { "changefeed": { "description": "The changefeed to create. All required fields must be set.", "allOf": [ { "$ref": "#/definitions/v1beta2Changefeed" } ] }, "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" ] }, "v1beta2DownstreamType": { "type": "string", "enum": [ "DOWNSTREAM_TYPE_UNSPECIFIED", "KAFKA", "MYSQL", "S3" ], "default": "DOWNSTREAM_TYPE_UNSPECIFIED", "description": "The downstream type for a changefeed.\n\n - DOWNSTREAM_TYPE_UNSPECIFIED: Default value. Should not be used.\n - KAFKA: Apache Kafka.\n - MYSQL: MySQL-compatible database.\n - S3: Amazon S3 or S3-compatible storage." }, "v1beta2EventFilter": { "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. Supported values include DML events such as `insert`, `update`, `delete`, and `all dml`, and DDL events such as `create schema`, `drop table`, `alter table`, and `all ddl`. For the complete list of supported values, see [Changefeed Log Filters](https://docs.pingcap.com/tidb/stable/ticdc-filter/)." }, "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 `tableMatchers` must contain all columns referenced in this expression." }, "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 `tableMatchers` must contain all columns referenced in this expression." }, "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 `tableMatchers` must contain all columns referenced in this expression." }, "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 `tableMatchers` must contain all columns referenced in this expression." } }, "description": "The event filter configuration for fine-grained control." }, "v1beta2KafkaDownstreamConfig": { "type": "object", "properties": { "broker": { "description": "The Kafka broker connection configuration.", "allOf": [ { "$ref": "#/definitions/KafkaDownstreamConfigBroker" } ] }, "authentication": { "description": "The Kafka authentication configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfigAuthentication" } ] }, "dataFormat": { "description": "The Kafka data format and serialization configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfigDataFormat" } ] }, "topicPartitionConfig": { "description": "The Kafka topic and partition configuration.", "allOf": [ { "$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" ] }, "v1beta2KafkaDownstreamConfigAuthentication": { "type": "object", "properties": { "authType": { "example": "SASL_SCRAM_SHA_256", "description": "The Kafka authentication type. This field is required, and the API does not provide a default authentication type. Specify one of the following values.\n\n- `\"DISABLE\"`: No authentication.\n\n- `\"SASL_PLAIN\"`: SASL/PLAIN authentication.\n\n- `\"SASL_SCRAM_SHA_256\"`: SASL/SCRAM-SHA-256 authentication.\n\n- `\"SASL_SCRAM_SHA_512\"`: SASL/SCRAM-SHA-512 authentication.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfigAuthenticationAuthType" } ] }, "username": { "type": "string", "example": "kafka_user", "description": "The SASL username for Kafka authentication." }, "password": { "type": "string", "example": "********", "description": "The SASL password for Kafka authentication." } }, "description": "The Kafka authentication configuration.", "required": [ "authType" ] }, "v1beta2KafkaDownstreamConfigAuthenticationAuthType": { "type": "string", "enum": [ "DISABLE", "SASL_PLAIN", "SASL_SCRAM_SHA_256", "SASL_SCRAM_SHA_512" ], "description": "AuthType defines the supported Kafka authentication types.\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." }, "v1beta2KafkaDownstreamConfigCompressionType": { "type": "string", "enum": [ "NONE", "GZIP", "SNAPPY", "LZ4", "ZSTD" ], "default": "NONE", "description": "CompressionType defines the compression types for Kafka messages.\n\n - NONE: No compression.\n - GZIP: GZIP compression.\n - SNAPPY: Snappy compression.\n - LZ4: LZ4 compression.\n - ZSTD: ZSTD compression." }, "v1beta2KafkaDownstreamConfigDataFormat": { "type": "object", "properties": { "protocol": { "example": "PROTOCOL_CANAL_JSON", "description": "The Kafka output protocol. This field is required, and the API does not provide a default protocol. Specify one of the following values.\n\n- `\"PROTOCOL_CANAL_JSON\"`: Canal JSON format. Recommended for most use cases.\n\n- `\"PROTOCOL_OPEN_PROTOCOL\"`: Open Protocol (TiDB native format). Encodes multiple events into one message.\n\n- `\"PROTOCOL_AVRO\"`: Apache Avro format.\n\n- `\"PROTOCOL_DEBEZIUM\"`: Debezium JSON format.\n\n- `\"PROTOCOL_DEBEZIUM_AVRO\"`: Debezium events encoded with Avro.", "allOf": [ { "$ref": "#/definitions/v1beta2KafkaDownstreamConfigDataFormatProtocol" } ] }, "debeziumConfig": { "description": "The Debezium-specific data format configuration.", "allOf": [ { "$ref": "#/definitions/DataFormatDebeziumConfig" } ] }, "avroConfig": { "description": "The Avro-specific data format configuration.", "allOf": [ { "$ref": "#/definitions/DataFormatAvroConfig" } ] }, "enableTidbExtension": { "type": "boolean", "example": true, "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." }, "outputRawChangeEvent": { "type": "boolean", "example": false, "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-transaction-by-memory." } }, "description": "The Kafka message format and serialization configuration.", "required": [ "protocol" ] }, "v1beta2KafkaDownstreamConfigDataFormatProtocol": { "type": "string", "enum": [ "PROTOCOL_CANAL_JSON", "PROTOCOL_OPEN_PROTOCOL", "PROTOCOL_AVRO", "PROTOCOL_DEBEZIUM", "PROTOCOL_DEBEZIUM_AVRO" ], "description": "Protocol defines the supported output protocols.\n\n - PROTOCOL_CANAL_JSON: Canal JSON format. Recommended for most use cases.\n - PROTOCOL_OPEN_PROTOCOL: Open Protocol (TiDB native format). Encodes multiple events into one message.\n - PROTOCOL_AVRO: Apache Avro format. Supports Confluent Schema Registry and AWS Glue Schema Registry.\n - PROTOCOL_DEBEZIUM: Debezium format.\n - PROTOCOL_DEBEZIUM_AVRO: Debezium events encoded with Avro." }, "v1beta2ListCCUsResponse": { "type": "object", "properties": { "ccus": { "type": "array", "items": { "$ref": "#/definitions/v1beta2ChangefeedCCU" }, "description": "The list of available CCU options.", "readOnly": true } }, "description": "The response for listing changefeed CCU options." }, "v1beta2ListChangefeedsResponse": { "type": "object", "properties": { "changefeeds": { "type": "array", "items": { "$ref": "#/definitions/v1beta2Changefeed" }, "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 } }, "description": "The response for listing changefeeds." }, "v1beta2MySQLDownstreamConfig": { "type": "object", "properties": { "connection": { "description": "The MySQL connection configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2Connection" } ] } }, "description": "The MySQL downstream configuration.", "required": [ "connection" ] }, "v1beta2NetworkInfo": { "type": "object", "properties": { "networkType": { "example": "NETWORK_TYPE_PUBLIC", "description": "The network type for downstream connectivity.\n\n- `\"NETWORK_TYPE_UNSPECIFIED\"`: Default value.\n\n- `\"NETWORK_TYPE_PUBLIC\"`: Public internet access.\n\n- `\"NETWORK_TYPE_VPC_PEERING\"`: AWS VPC Peering.\n\n- `\"NETWORK_TYPE_PRIVATE_LINK\"`: Private endpoint connectivity managed by TiDB Cloud. Create a private endpoint for the external service in the console UI and assign it to `sinkEndpointId`.", "allOf": [ { "$ref": "#/definitions/NetworkInfoNetworkType" } ] }, "sinkEndpointId": { "type": "string", "format": "uint64", "example": "12345", "description": "The ID of the downstream network endpoint for an external service. Required when `networkType` is `NETWORK_TYPE_PRIVATE_LINK`." }, "ports": { "type": "array", "example": [ 9092 ], "items": { "type": "integer", "format": "int64" }, "description": "The ports for private endpoint connectivity. Required when networkType is `NETWORK_TYPE_PRIVATE_LINK`. The server uses these ports to construct broker endpoints as `:`." } }, "description": "The network configuration for downstream connectivity.", "required": [ "networkType" ] }, "v1beta2S3DataFormat": { "type": "object", "properties": { "protocol": { "example": "PROTOCOL_CANAL_JSON", "description": "The output protocol. This field is required, and the API does not provide a default protocol. Specify one of the following values.\n\n- `\"PROTOCOL_CSV\"`: CSV format.\n\n- `\"PROTOCOL_CANAL_JSON\"`: Canal JSON format.", "allOf": [ { "$ref": "#/definitions/v1beta2S3DataFormatProtocol" } ] }, "terminator": { "type": "string", "example": "\n", "description": "The row terminator used to separate data change events. This configuration is only used for storage sinks. The default value is a newline character (\"\\n\"). When the field is omitted or empty, a newline is used." }, "dateSeparator": { "example": "DAY", "description": "The date separator for the directory structure. The default value is `NONE`.\n\n- `\"NONE\"`: No date separator.\n\n- `\"YEAR\"`: Separate by year.\n\n- `\"MONTH\"`: Separate by month.\n\n- `\"DAY\"`: Separate by day.", "allOf": [ { "$ref": "#/definitions/S3DataFormatDateSeparator" } ] }, "enableTidbExtension": { "type": "boolean", "example": false, "description": "Indicates whether to enable TiDB extension fields in Canal-JSON messages. The default value is false." }, "delimiter": { "type": "string", "example": ",", "description": "The field delimiter for CSV files. Required when protocol is `PROTOCOL_CSV`. The value must be an ASCII character." }, "quote": { "type": "string", "example": "\"", "description": "The quotation character for CSV fields. The default value is `\"`. When the value is empty, the default quotation character is retained." }, "null": { "type": "string", "example": "NULL", "description": "The null representation for CSV columns. The default value is `\\N`." }, "includeCommitTs": { "type": "boolean", "example": false, "description": "Indicates whether to include the commit timestamp in CSV rows. The default value is false." }, "binaryEncodingMethod": { "example": "BASE64", "description": "The binary encoding method. The default value is `BASE64`.\n\n- `\"BASE64\"`: Base64 encoding.\n\n- `\"HEX\"`: Hexadecimal encoding.", "allOf": [ { "$ref": "#/definitions/S3DataFormatBinaryEncodingMethod" } ] }, "outputRawChangeEvent": { "type": "boolean", "example": false, "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-transaction-by-memory." }, "outputFieldHeader": { "type": "boolean", "example": false, "description": "Indicates whether to include the CSV field header. The default value is false." } }, "description": "The S3 data format configuration.", "required": [ "protocol" ] }, "v1beta2S3DataFormatProtocol": { "type": "string", "enum": [ "PROTOCOL_CSV", "PROTOCOL_CANAL_JSON" ], "description": "Protocol defines the supported output protocols for cloud storage sinks.\n\n - PROTOCOL_CSV: CSV format.\n - PROTOCOL_CANAL_JSON: Canal JSON format." }, "v1beta2S3DownstreamConfig": { "type": "object", "properties": { "endpoint": { "description": "The S3 endpoint configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2S3DownstreamConfigEndpoint" } ] }, "dataFormat": { "description": "The S3 data format configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2S3DataFormat" } ] }, "storageFlushConfig": { "description": "The storage flush configuration.", "allOf": [ { "$ref": "#/definitions/v1beta2StorageFlushConfig" } ] } }, "description": "The S3 downstream configuration.", "required": [ "endpoint", "dataFormat" ] }, "v1beta2S3DownstreamConfigEndpoint": { "type": "object", "properties": { "s3Uri": { "type": "string", "example": "s3://my-bucket/cdc-data/", "description": "The S3 bucket URI. For example, `s3://bucket/prefix/`. The URI must end with a trailing slash.\n\nFor Alibaba Cloud OSS, use the S3-compatible URI format `s3://{bucket_name}/{prefix}/`. Do not use the raw OSS URI format." }, "authType": { "example": "S3_AUTH_TYPE_AK_SK", "description": "The S3 authentication type. This field is required, and the API does not provide a default authentication type. Specify one of the following values.\n\n- `\"S3_AUTH_TYPE_AK_SK\"`: Access Key / Secret Key authentication.\n\n- `\"S3_AUTH_TYPE_ASSUME_ROLE\"`: IAM Assume Role authentication.\n\nFor Alibaba Cloud OSS, only `S3_AUTH_TYPE_AK_SK` is currently supported.", "allOf": [ { "$ref": "#/definitions/EndpointS3AuthType" } ] }, "accessKey": { "type": "string", "example": "AKIAIOSFODNN7EXAMPLE", "description": "The access key for S3 authentication. This field is required when authType is S3_AUTH_TYPE_AK_SK." }, "secretKey": { "type": "string", "example": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "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." }, "iamAssumedRoleArn": { "type": "string", "example": "arn:aws:iam::123456789012:role/CDCS3AccessRole", "description": "The IAM assumed role ARN for S3 authentication. This field is required when authType is S3_AUTH_TYPE_ASSUME_ROLE." }, "customEndpoint": { "type": "string", "example": "https://s3.oss-{region_id}.aliyuncs.com", "description": "The custom S3-compatible endpoint. Required for Alibaba OSS." }, "provider": { "example": "AWS", "description": "The object storage provider. If omitted or set to `\"PROVIDER_UNSPECIFIED\"`, AWS S3 behavior is used.\n\n- `\"AWS\"`: Amazon S3.\n\n- `\"ALIBABA_OSS\"`: Alibaba Cloud OSS through its S3-compatible endpoint.", "allOf": [ { "$ref": "#/definitions/EndpointProvider" } ] } }, "description": "The S3 endpoint configuration.", "required": [ "s3Uri", "authType" ] }, "v1beta2StartPosition": { "type": "object", "properties": { "mode": { "example": "FROM_NOW", "description": "The start position mode.\n\n- `\"MODE_UNSPECIFIED\"`: Default value.\n\n- `\"FROM_NOW\"`: Start from the current time.\n\n- `\"FROM_TSO\"`: Start from a specific TSO.\n\n- `\"FROM_UTC\"`: Start from a specific UTC timestamp.", "allOf": [ { "$ref": "#/definitions/v1beta2StartPositionMode" } ] }, "startTso": { "type": "string", "format": "uint64", "example": "452348901234567890", "description": "The start TSO. This field is required when the mode is `FROM_TSO`." }, "startTimestamp": { "type": "string", "example": "2026-01-01T00:00:00Z", "description": "The start UTC timestamp in RFC 3339 format. This field is required when the mode is `FROM_UTC`." } }, "description": "The start position for the changefeed.", "required": [ "mode" ] }, "v1beta2StartPositionMode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "FROM_NOW", "FROM_TSO", "FROM_UTC" ], "default": "MODE_UNSPECIFIED", "description": "Mode defines the start position mode.\n\n - MODE_UNSPECIFIED: Default value.\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." }, "v1beta2StorageFlushConfig": { "type": "object", "properties": { "interval": { "type": "string", "example": "1m", "description": "The flush interval as a duration string. 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. Data is flushed when this size is reached. 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." }, "v1beta2TableConfig": { "type": "object", "properties": { "filterRules": { "type": "array", "example": [ "mydb.orders", "mydb.user_*", "!mydb.secret_*" ], "items": { "type": "string" }, "description": "The table filter rules. For example: `[\"mydb.orders\", \"mydb.user_*\", \"!mydb.secret_*\"]` Refer [TiCDC Table Filter](https://docs.pingcap.com/tidb/stable/ticdc-filter/#table-filter) for supported syntax." }, "mode": { "example": "FORCE_SYNC", "description": "The mode for handling unsupported tables.\n\n- `\"MODE_UNSPECIFIED\"`: Default value. Must not be used.\n\n- `\"IGNORE_NOT_SUPPORT_TABLE\"`: Skip unsupported tables silently.\n\n- `\"FORCE_SYNC\"`: Force sync all tables (may fail on unsupported tables).", "allOf": [ { "$ref": "#/definitions/v1beta2TableConfigMode" } ] }, "caseSensitive": { "type": "boolean", "description": "Indicates whether the filter rules are case-sensitive. The default value is false." }, "eventFilters": { "type": "array", "items": { "$ref": "#/definitions/v1beta2EventFilter" }, "description": "The event filter rules for fine-grained control." }, "bdrMode": { "type": "boolean", "description": "Indicates whether [bidirectional replication mode](https://docs.pingcap.com/tidb/stable/ticdc-bidirectional-replication/) is enabled." } }, "description": "The table filtering and event filter configuration.", "required": [ "mode" ] }, "v1beta2TableConfigMode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "IGNORE_NOT_SUPPORT_TABLE", "FORCE_SYNC" ], "default": "MODE_UNSPECIFIED", "description": "Mode defines how to handle tables that are not supported by the changefeed.\n\n - MODE_UNSPECIFIED: Default value.\n - IGNORE_NOT_SUPPORT_TABLE: Skip unsupported tables silently.\n - FORCE_SYNC: Force sync all tables (may fail on unsupported tables)." }, "TidbServiceCreateTidbBackupBody": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the manual backup." } }, "required": [ "name" ] }, "v1beta2CreateTidbBackupResponse": { "type": "object", "properties": { "backupId": { "type": "string", "example": "1234567890", "description": "The ID of the created backup.", "readOnly": true } }, "required": [ "backupId" ] } }, "x-tagGroups": [ { "name": "Endpoints", "tags": [ "TiDB Cloud Premium Instance", "Backup", "Region", "Changefeed" ] } ] }