openapi: 3.2.0
info:
title: TiDB Cloud Data Service OPEN Endpoint API
description: "# Overview\n\nThe TiDB Cloud Data Service API provides a [RESTful interface](https://en.wikipedia.org/wiki/Representational_state_transfer) for programmatically managing administrative objects within the [TiDB Cloud Data Service](https://docs.pingcap.com/tidbcloud/data-service-overview). Through this API, you can manage the following resources automatically and efficiently:\n\n* **Data App**: a collection of endpoints that you can use to access data for a specific application.\n* **Data Source**: clusters linked to Data Apps for data manipulation and retrieval.\n* **Endpoint**: a web API that you can customize to execute SQL statements. You can specify parameters for the SQL statements, such as the value used in the `WHERE` clause. When a client calls an endpoint and provides values for the parameters in a request URL, the endpoint executes the SQL statement with the provided parameters and returns the results as part of the HTTP response.\n* **Deployment**: the process of deploying Data Apps.\n* **Data API Key**: used for secure endpoint access. This key is used to access data in the TiDB Cloud clusters, whereas the TiDB Cloud organization API key is used to manage resources such as projects, clusters, Data Apps, and endpoints.\n* **OpenAPI Specification**: Data Service supports generating the OpenAPI Specification 3.0 for each Data App, which enables you to interact with your endpoints in a standardized format. You can use this specification to generate standardized OpenAPI documentation, client SDKs, and server stubs.\n\n# Get Started\n\nThis guide helps you make your first API call to TiDB Cloud Data Service API. You'll learn how to authenticate a request, build a request, and interpret the response. The [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint is used in this guide as an example.\n\n## Prerequisites\n\nTo complete this guide, you need to perform the following tasks:\n\n- Create a [TiDB Cloud account](https://tidbcloud.com/free-trial)\n- Install [curl](https://curl.se/)\n\n## Step 1. Create an organization API key\n\nTo create an organization API key, log in to your TiDB Cloud console. Navigate to the [**API Keys**](https://tidbcloud.com/org-settings/api-keys) page of your organization, and create an API key.\n\nAn organization API key contains a public key and a private key. Copy and save them in a secure location. You will need to use the API key later in this guide.\n\nFor more details about creating an organization API key, refer to [API Key Management](#section/Authentication/API-Key-Management).\n\n## Step 2. Make your first API call\n\n### Build an API call\n\nTiDB Cloud Data Service API call consists of the following components:\n\n- **A host.** The host for TiDB Cloud Data Service API is <https://dataservice.tidbapi.com>.\n- **An organization API Key**. The public key and the private key are required for authentication.\n- **A request.** When submitting data to a resource via `POST`, `PATCH`, or `PUT`, you must submit your payload in JSON.\n\nIn this guide, you call the [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint. For a detailed description of the endpoint, see the [API reference](#tag/Data-App/operation/DataApp_ListDataApps).\n\n### Call an API endpoint\n\nTo get all Data Apps in your project, run the following command in your terminal. Replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_PROJECT_ID` with your actual values. To get the project ID, you can call the [List all accessible projects](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/ListProjects) endpoint.\n\n```bash\ncurl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps?projectId=YOUR_PROJECT_ID'\n```\n\n## Step 3. Check the response\n\nAfter making the API call, if the status code in response is `200` and you see details about all the Data Apps in your project, your request is successful. Here is an example of a successful response.\n\n```log\n{\n \"dataApps\": [\n {\n \"dataAppId\": \"{data_app_id}\",\n \"name\": \"dataApps/{data_app_id}\",\n \"version\": \"\",\n \"projectId\": \"{project_id}\",\n \"clusterIds\": [],\n \"appType\": \"DATAAPP\",\n \"displayName\": \"New Data App\",\n \"description\": \"\",\n \"createdAt\": \"2023-06-03T06:52:08Z\",\n \"updatedAt\": \"2023-06-03T06:52:08Z\"\n },\n {\n \"dataAppId\": \"{data_app_id}\",\n \"name\": \"dataApps/{data_app_id}\",\n \"version\": \"\",\n \"projectId\": \"{project_id}\",\n \"clusterIds\": [],\n \"appType\": \"CHAT2QUERY\",\n \"displayName\": \"New App\",\n \"description\": \"\",\n \"createdAt\": \"2023-06-03T06:52:08Z\",\n \"updatedAt\": \"2023-06-03T06:52:08Z\"\n }\n ],\n \"nextPageToken\": \"\"\n}\n```\n\nIf your API call is not successful, you will receive a status code other than `200` and the response looks similar to the following example. To troubleshoot the failed call, you can check the `message` in the response.\n\n```log\n{\n \"code\": 403,\n \"message\": \"Request error, projectId not exist\",\n \"details\": []\n}\n```\n\n# Call a Deployed Data Service Endpoint\n\nIf you have deployed a Data Service endpoint, you can call it using the Data API key. To begin, follow these steps:\n\n1. Generate a Data API key by calling the [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey) endpoint. You can run the following `curl` command and replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_DATAAPP_ID` with your actual values. Note that `YOUR_PUBLIC_KEY` and `YOUR_PRIVATE_KEY` are [organization API keys](#section/Authentication/Organization-API-key-overview).\n\n ```bash\n curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/YOUR_DATAAPP_ID/apiKeys'\\\n --header 'Content-Type: application/json' \\\n --data '{\n \"description\": \"A new API Key\",\n \"role\": \"READ_AND_WRITE\",\n \"rateLimitRpm\": 100\n }'\n ```\n\n2. Call the deployed endpoint. Suppose that you have created a `GET` endpoint named `/hello`, with the request URL as `https://data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello`. To call this endpoint, replace `YOUR_DATAAPP_PUBLIC_KEY` and `YOUR_DATAAPP_PRIVATE_KEY` with the values obtained from the response in step 1, and replace `YOUR_DATAAPP_ID` with the actual Data App ID in the following command:\n\n ```bash\n curl --location-trusted --digest \\\n --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://data.tidbcloud.com/api/v1beta/app/YOUR_DATAAPP_ID/endpoint/hello'\n ```\n \n For improved performance, you can call the endpoint using the regional domain name. Replace `REGION` with the specific region name to which the cluster belongs, such as `us-west-2`.\n \n ```bash\n curl --digest \\\n --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://REGION.data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello'\n ```\n\n# Authentication\n\nThe TiDB Cloud Data Service 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## Organization API key overview\n\n- The organization 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 organization 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 organization API key in every request. Otherwise, TiDB Cloud responds with a `401` error.\n\n## Organization API key management\n\n### Create an organization API key\n\nOnly the **owner** of an organization can create an organization API key.\n\nTo create an organization 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. The role of the API key is always `Organization Owner` currently.\n5. Click **Next**. Copy and save the public key and the private key.\n6. 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.\n7. Click **Done**.\n\n### View details of an organization API key\n\nTo view details of an organization 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 organization API key\n\nOnly the **owner** of an organization can modify an organization API key.\n\nTo edit an organization 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 **Edit**.\n4. You can update the API key description.\n5. Click **Update**.\n\n### Delete an organization API key\n\nOnly the **owner** of an organization can delete an organization API key.\n\nTo delete an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to delete, and then click **Delete**.\n4. Click **I understand, delete it.**\n\n# Rate Limiting\n\nThe TiDB Cloud Data Service API allows up to 100 requests per minute per API key. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519) to contact our support team.\n\nEach API request returns the following headers about the limit.\n\n- `X-Ratelimit-Limit-Minute`: The number of requests allowed per minute. It is 100 currently.\n- `X-Ratelimit-Remaining-Minute`: The number of remaining requests in the current minute. When it reaches `0`, the API returns a `429` error and indicates that you exceed the rate limit.\n- `X-Ratelimit-Reset`: The time in seconds at which the current rate limit resets.\n\nIf you exceed the rate limit, an error response returns like this.\n\n```\n> HTTP/2 429\n> date: Fri, 22 Jul 2022 05:28:37 GMT\n> content-type: application/json\n> content-length: 66\n> x-ratelimit-reset: 23\n> x-ratelimit-remaining-minute: 0\n> x-ratelimit-limit-minute: 100\n> x-kong-response-latency: 2\n> server: kong/2.8.1\n\n> {\"details\":[],\"code\":49900007,\"message\":\"The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519\"}\n```\n\n# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud Data Service API.\n\n<!-- In reverse chronological order -->\n\n## 20250812\n\n- \"TiDB Cloud Serverless\" is renamed to \"TiDB Cloud Starter\".\n\n## 20240910\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for the `gpt-3.5-turbo` model and adds support for `gpt-4o` and `gpt-4o-mini` models.\n\n- \"TiDB Serverless\" is renamed to \"TiDB Cloud Serverless\".\n- \"TiDB Dedicated\" is renamed to \"TiDB Cloud Dedicated\".\n\n## 20240806\n\n- Add the [List all system endpoints in a Data App](#tag/Data-App/operation/DataAppsService_GetSystemEndpointConfig) endpoint.\n\n- Add the [Update the configuration of system endpoints](#tag/Data-App/operation/DataAppsService_UpdateSystemEndpointConfig) endpoint.\n\n## 20240716\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for Claude models.\n\n## 20240528\n\n- Initial release of the TiDB Cloud Data Service API, including the following resources and endpoints:\n\n - Data App:\n - [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps)\n - [Create a Data App](#tag/Data-App/operation/DataApp_CreateDataApp)\n - [Get Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_GetChat2QuerySettings)\n - [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings)\n - [Update a Data App](#tag/Data-App/operation/DataApp_UpdateDataApp)\n - [Get a Data App by ID](#tag/Data-App/operation/DataApp_GetDataApp)\n - [Delete a Data App](#tag/Data-App/operation/DataApp_DeleteDataApp)\n - Data Source:\n - [List all data sources in a Data App](#tag/Data-Source/operation/DataSource_ListDataSources)\n - [Create a data source for a Data App](#tag/Data-Source/operation/DataSource_CreateDataSource)\n - [Get a data source by ID](#tag/Data-Source/operation/DataSource_GetDataSource)\n - [Delete a data source for a Data App](#tag/Data-Source/operation/DataSource_DeleteDataSource)\n - Endpoint:\n - [List all endpoints in a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n - [Create an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_CreateEndpoint)\n - [Update an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_UpdateEndpoint)\n - [Get an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_GetEndpoint)\n - [Delete an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_DeleteEndpoint)\n - [Test an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_TestEndpoint)\n - Deployment:\n - [List all deployments for a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n - [Create a deployment for a Data App](#tag/Deployment/operation/Deployment_CreateDeployment)\n - [Get a deployment by ID](#tag/Deployment/operation/Deployment_GetDeployment)\n - Data API Key:\n - [List all API keys for a Data App](#tag/Data-API-Key/operation/APIKey_ListApiKeys)\n - [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey)\n - [Update an API key for a Data App](#tag/Data-API-Key/operation/APIKey_UpdateApiKey)\n - [Get an API key by ID](#tag/Data-API-Key/operation/APIKey_GetApiKey)\n - [Delete an API key for a Data App](#tag/Data-API-Key/operation/APIKey_DeleteApiKey)\n - OpenAPI Specification:\n - [Get the OpenAPI Specification of a Data App](#tag/OpenAPI-Specification/operation/APISpecification_GetApiSpec)\n"
version: v1beta1
servers:
- url: https://dataservice.tidbapi.com
tags:
- name: Endpoint
description: Create, get, delete, list, and test endpoints of a Data App.
paths:
/v1beta1/dataApps/{dataAppId}/endpoints:
get:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/endpoints?pageSize=5'"
summary: List all endpoints in a Data App.
operationId: Endpoint_ListEndpoints
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1ListEndpointsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: dataAppId
description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
in: path
required: true
schema:
type: string
- name: pageSize
description: The maximum number of items to return. If it is not set or set to `0`, the default value `100` will be used.
in: query
required: false
schema:
type: integer
format: int32
default: 100
maximum: 100
minimum: 1
- name: pageToken
description: The identifier of the current page, used to retrieve the next page of results. You can get this value from the `nextPageToken` field in the previous response. To access the first page of data, omit this field.
in: query
required: false
schema:
type: string
tags:
- Endpoint
post:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/endpoints' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"displayName\": \"/v1/hello\", \n \"description\": \"/v1/hello endpoint\", \n \"path\": \"/v1/hello\", \n \"method\": \"GET\", \n \"clusterId\": \"{clusterId}\", \n \"settings\": {\n \"timeout\": 30000, \n \"rowLimit\": 2000, \n \"paginationEnabled\": false, \n \"cacheEnabled\": false\n }, \n \"tag\": \"Default\", \n \"sqlTemplate\": \"select 'Hello World';\" \n }'"
summary: Create an endpoint for a Data App.
operationId: Endpoint_CreateEndpoint
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1EndpointRes'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: dataAppId
description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
in: path
required: true
schema:
type: string
tags:
- Endpoint
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1Endpoint'
description: Endpoint
required: true
/v1beta1/dataApps/{endpoint.name}:
patch:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request PATCH \\\n --url 'https://dataservice.tidbapi.com/v1beta1/{endpoint.name}' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"displayName\": \"/v2/hello\", \n \"description\": \"/v2/hello endpoint\", \n \"path\": \"/v2/hello\", \n \"method\": \"GET\", \n \"clusterId\": \"{clusterId}\", \n \"settings\": {\n \"timeout\": 30000, \n \"rowLimit\": 2000, \n \"paginationEnabled\": false, \n \"cacheEnabled\": false\n }, \n \"tag\": \"V2\", \n \"sqlTemplate\": \"select 'Hello World New';\" \n }'"
summary: Update an endpoint for a Data App.
operationId: Endpoint_UpdateEndpoint
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1EndpointRes'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: endpoint.name
description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
in: path
required: true
schema:
type: string
pattern: dataApps/[^/]+/endpoints/[^/]+
tags:
- Endpoint
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1Endpoint'
description: 'To update an endpoint, specify the following fields as needed:'
required: true
get:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/{endpoint.name}'"
summary: Get an endpoint for a Data App.
operationId: Endpoint_GetEndpoint
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1EndpointRes'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: endpoint.name
description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
in: path
required: true
schema:
type: string
pattern: dataApps/[^/]+/endpoints/[^/]+
tags:
- Endpoint
delete:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request DELETE \\\n --url 'https://dataservice.tidbapi.com/v1beta1/{endpoint.name}'"
summary: Delete an endpoint for a Data App.
description: Before you delete an endpoint, make sure that the endpoint is not online. Otherwise, the endpoint cannot be deleted.
operationId: Endpoint_DeleteEndpoint
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: endpoint.name
description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
in: path
required: true
schema:
type: string
pattern: dataApps/[^/]+/endpoints/[^/]+
tags:
- Endpoint
/v1beta1/{endpoint.name}/test:
post:
x-code-samples:
- lang: Curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://dataservice.tidbapi.com/v1beta1/{endpoint.name}/test' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n \"args\": [\n {\n \"items\": {}\n }\n ] \n }'"
summary: Test an endpoint for a Data App.
operationId: Endpoint_TestEndpoint
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/v1beta1TestEndpointResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: endpoint.name
description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
in: path
required: true
schema:
type: string
pattern: dataApps/[^/]+/endpoints/[^/]+
tags:
- Endpoint
requestBody:
content:
application/json:
schema:
type: object
properties:
args:
type: array
items:
$ref: '#/components/schemas/v1beta1EndpointArgs'
required:
- args
description: The parameter values used for testing the endpoint.
required: true
components:
schemas:
v1beta1TestEndpointResponse:
type: object
properties:
type:
type: string
description: Endpoint's type.
data:
$ref: '#/components/schemas/TestEndpointResponseData'
description: The response of testing the endpoint.
title: Response for TestEndpoint
TestEndpointResponseData:
type: object
properties:
columns:
type: array
items:
$ref: '#/components/schemas/TestEndpointResponseColumn'
description: Returns the columns and columns' details of the requested data table of the endpoint.
rows:
type: array
items:
$ref: '#/components/schemas/TestEndpointResponseRow'
description: Return the columns and data results of the requested data table of the endpoint.
result:
$ref: '#/components/schemas/TestEndpointResponseResult'
title: Endpoint request data
v1beta1ListEndpointsResponse:
type: object
properties:
endpoints:
type: array
items:
$ref: '#/components/schemas/v1beta1EndpointRes'
description: The items of endpoints in the Data App.
nextPageToken:
type: string
description: The token to retrieve the next page of results.
title: Response for ListEndpoint
TestEndpointResponseColumn:
type: object
properties:
col:
type: string
description: The column name of the requested data table.
dataType:
type: string
description: The column type of the requested data table.
nullable:
type: boolean
description: Whether the column of the requested data table supports null values.
v1beta1EndpointSettingsRes:
type: object
properties:
timeout:
type: integer
format: int32
description: The user-defined timeout for the endpoint in milliseconds.
minimum: 1
maximum: 60000
rowLimit:
type: integer
format: int32
description: The maximum number of rows that the endpoint can operate or return.
minimum: 1
maximum: 2000
paginationEnabled:
type: boolean
description: Controls whether to enable the pagination for the results returned by the `GET` request. When pagination is enabled, you can paginate the results by specifying `page` and `page_size` as query parameters when calling the endpoint.
cacheEnabled:
type: boolean
description: Controls whether to cache the response returned by your `GET` requests within a specified time-to-live (TTL) period.
cacheTtl:
type: integer
format: int32
description: The time-to-live (TTL) period in seconds for cached response when `cacheEnabled` is set to `true`.
minimum: 30
maximum: 600
description: The settings used in the endpoint.
v1beta1EndpointRes:
type: object
properties:
name:
type: string
description: The unique identifier for the endpoint, which is generated by the API and follows the format `dataApps/{dataAppId}/endpoints/{endpointId}`.
status:
type: string
description: 'The deployment status of the endpoint:
- `"deployed"`: the endpoint has been successfully deployed
- `"draft"`: the endpoint is currently a draft and has not been deployed yet'
displayName:
type: string
description: The name of the endpoint. By default, it is the same as the `path` value. You can update the name using [Update an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_UpdateEndpoint).
description:
type: string
description: The user-defined description of the endpoint.
path:
type: string
description: 'The user-defined HTTP path of the endpoint in the Data App. A path must start with a slash (`/`). For example: `/v1/hello`.'
method:
type: string
description: 'The user-defined HTTP method of the endpoint. The supported HTTP methods are: `GET`, `POST`, `PUT`, and `DELETE`.'
clusterId:
type: string
description: The ID of the TiDB cluster that is linked to the endpoint.
params:
type: array
items:
$ref: '#/components/schemas/v1beta1EndpointParamsRes'
description: The parameters used in the endpoint.
settings:
$ref: '#/components/schemas/v1beta1EndpointSettingsRes'
description: The settings used in the endpoint.
tag:
type: string
description: The tag used for identifying a group of endpoints.
default: Default
batchOperation:
type: boolean
description: Controls whether to enable the endpoint to operate in batch mode. When it is set to `true`, you can operate on multiple rows in a single request.
sqlTemplate:
type: string
description: Specifies the SQL statements to query data through the endpoint.
type:
type: string
description: The type of the endpoint, which cannot be set by the user.
default: sql_endpoint
returnType:
type: string
description: The response format of the endpoint. Currently, only JSON is supported, represented by the value "json". There is no need for user configuration.
createdAt:
type: string
description: 'The timestamp when the endpoint was created. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
updatedAt:
type: string
description: 'The timestamp when the endpoint was last updated. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
TestEndpointResponseResult:
type: object
properties:
code:
type: integer
format: int32
description: HTTPS status code of the request.
message:
type: string
description: HTTPS result message of the request. If the status code returned by the request is 200, OK is returned here. If there is an error in the request, the specific reason for the error is returned.
startMs:
type: string
format: int64
description: 'The request''s start timestamp. For example: 1704871891280'
endMs:
type: string
format: int64
description: 'The request''s end timestamp. For example: 1704871891474'
latency:
type: string
description: 'The request latency. For example: 194ms'
rowCount:
type: integer
format: int32
description: The number of rows that the request should return. Sometimes the maximum number of returned rows set by the user is exceeded. But in the end, only the number of rows returned is the minimum of these two
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pingcap/refs/heads/main/openapi/pingcap-endpoint-api-openapi.yml