openapi: 3.1.0
info:
title: TiDB Cloud Data Service API
description: >-
The TiDB Cloud Data Service API enables developers to manage Data Apps and
custom REST endpoints backed by SQL queries running against TiDB Cloud
clusters. Operators create Data Apps, link them to clusters, define custom
endpoints with SQL templates, manage API keys, and deploy endpoints via this
API. Endpoints support GET, POST, PUT, and DELETE methods, return
JSON-formatted results, and can be configured with pagination, rate limiting,
and caching. The API uses HTTP Digest Authentication and is served from the
dataservice.tidbapi.com host.
version: v1beta1
contact:
name: TiDB Cloud Support
url: https://docs.pingcap.com/tidbcloud/data-service-overview/
termsOfService: https://www.pingcap.com/legal/privacy-policy/
externalDocs:
description: TiDB Cloud Data Service Overview
url: https://docs.pingcap.com/tidbcloud/data-service-overview/
servers:
- url: https://dataservice.tidbapi.com/v1beta1
description: Data Service Management API Server
tags:
- name: Data App API Keys
description: Operations for managing API keys scoped to a specific Data App.
- name: Data Apps
description: Operations for creating, listing, updating, and deleting Data Apps.
- name: Data Sources
description: Operations for linking and managing TiDB Cloud clusters as data sources within a Data App.
- name: Deployments
description: Operations for deploying and managing versions of a Data App.
- name: Endpoints
description: Operations for creating, listing, updating, testing, and deleting custom SQL-backed API endpoints.
security:
- digestAuth: []
paths:
/dataApps:
get:
operationId: listDataApps
summary: List Data Apps
description: >-
Returns a paginated list of all Data Apps in the organization. Each Data
App represents a collection of custom endpoints that are backed by SQL
queries running against linked TiDB Cloud clusters. Results include
the app ID, display name, description, and linked cluster information.
tags:
- Data Apps
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of Data Apps.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDataAppsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimitExceeded'
post:
operationId: createDataApp
summary: Create a Data App
description: >-
Creates a new Data App within the organization. A Data App is a container
for custom SQL-backed API endpoints. After creation, link a TiDB Cloud
cluster as a data source and define endpoints to begin serving data via
HTTPS.
tags:
- Data Apps
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataAppRequest'
responses:
'200':
description: Data App created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataApp'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/dataApps/{dataAppId}:
get:
operationId: getDataApp
summary: Get a Data App
description: >-
Returns the configuration and metadata for a specific Data App, including
its display name, description, linked data sources, system endpoint
configuration, and Chat2Query settings if enabled.
tags:
- Data Apps
parameters:
- $ref: '#/components/parameters/dataAppId'
responses:
'200':
description: Data App details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataApp'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateDataApp
summary: Update a Data App
description: >-
Updates the display name or description of an existing Data App. Only
the fields provided in the request body are modified. Linked data sources
and endpoints remain unchanged.
tags:
- Data Apps
parameters:
- $ref: '#/components/parameters/dataAppId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDataAppRequest'
responses:
'200':
description: Data App updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataApp'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteDataApp
summary: Delete a Data App
description: >-
Permanently deletes a Data App and all of its associated endpoints, API
keys, and deployment history. This operation is irreversible. All clients
calling endpoints within this Data App will receive errors after deletion.
tags:
- Data Apps
parameters:
- $ref: '#/components/parameters/dataAppId'
responses:
'200':
description: Data App deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/dataSources:
get:
operationId: listDataSources
summary: List data sources
description: >-
Returns all TiDB Cloud clusters linked as data sources to a specific Data
App. Each data source includes the cluster ID, cluster name, and the
databases accessible from this Data App.
tags:
- Data Sources
parameters:
- $ref: '#/components/parameters/dataAppId'
responses:
'200':
description: List of data sources retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDataSourcesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createDataSource
summary: Create a data source
description: >-
Links a TiDB Cloud cluster to a Data App as a data source. Once linked,
endpoints within the Data App can execute SQL queries against databases in
the linked cluster. A Data App can be linked to multiple clusters.
tags:
- Data Sources
parameters:
- $ref: '#/components/parameters/dataAppId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataSourceRequest'
responses:
'200':
description: Data source linked successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/dataSources/{clusterId}:
get:
operationId: getDataSource
summary: Get a data source
description: >-
Returns the configuration of a specific cluster linked as a data source
to a Data App, identified by the cluster ID.
tags:
- Data Sources
parameters:
- $ref: '#/components/parameters/dataAppId'
- $ref: '#/components/parameters/clusterId'
responses:
'200':
description: Data source details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataSource'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteDataSource
summary: Delete a data source
description: >-
Unlinks a TiDB Cloud cluster from a Data App. Endpoints that reference
this cluster will stop working after the data source is removed.
tags:
- Data Sources
parameters:
- $ref: '#/components/parameters/dataAppId'
- $ref: '#/components/parameters/clusterId'
responses:
'200':
description: Data source unlinked successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/endpoints:
get:
operationId: listEndpoints
summary: List endpoints
description: >-
Returns a paginated list of all custom SQL-backed endpoints defined within
a Data App. Each endpoint entry includes its HTTP method, path, SQL
template, parameters, and configuration settings such as caching and
pagination.
tags:
- Endpoints
parameters:
- $ref: '#/components/parameters/dataAppId'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of endpoints.
content:
application/json:
schema:
$ref: '#/components/schemas/ListEndpointsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createEndpoint
summary: Create an endpoint
description: >-
Defines a new custom SQL-backed API endpoint within a Data App. Specify
the HTTP method, URL path, target cluster, SQL template, and any path or
query parameters. The endpoint will become available after the Data App
is deployed.
tags:
- Endpoints
parameters:
- $ref: '#/components/parameters/dataAppId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEndpointRequest'
responses:
'200':
description: Endpoint created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/apiKeys:
get:
operationId: listDataAppApiKeys
summary: List Data App API keys
description: >-
Returns all API keys scoped to a specific Data App. These keys are used
to authenticate calls to the custom endpoints defined within the Data App
and are separate from organization-level API keys.
tags:
- Data App API Keys
parameters:
- $ref: '#/components/parameters/dataAppId'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: List of Data App API keys retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDataAppApiKeysResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createDataAppApiKey
summary: Create a Data App API key
description: >-
Creates a new API key scoped to a specific Data App. Specify the key
description, role (READ_ONLY or READ_AND_WRITE), rate limit in requests
per minute, and optional expiration settings. The private key is only
returned at creation time.
tags:
- Data App API Keys
parameters:
- $ref: '#/components/parameters/dataAppId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataAppApiKeyRequest'
responses:
'200':
description: Data App API key created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DataAppApiKey'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/deployments:
get:
operationId: listDeployments
summary: List deployments
description: >-
Returns a paginated list of deployment records for a Data App. Each
deployment captures a versioned snapshot of the Data App's endpoints
at the time of deployment, enabling rollback and audit of configuration
changes.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/dataAppId'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/pageToken'
responses:
'200':
description: A paginated list of deployments.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDeploymentsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createDeployment
summary: Create a deployment
description: >-
Deploys the current configuration of a Data App, making all defined
endpoints live. Creates an immutable deployment record that can be
referenced for rollback. Endpoints are not publicly accessible until
a successful deployment is created.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/dataAppId'
responses:
'200':
description: Data App deployed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/dataApps/{dataAppId}/apiSpec:
get:
operationId: getDataAppApiSpec
summary: Get OpenAPI specification
description: >-
Returns the OpenAPI 3.0 specification for all endpoints defined within
a Data App. The specification can be returned in JSON or YAML format
by setting the Accept header accordingly. Use this spec to generate
client SDKs, import into API testing tools, or publish API documentation.
tags:
- Data Apps
parameters:
- $ref: '#/components/parameters/dataAppId'
responses:
'200':
description: OpenAPI specification retrieved successfully.
content:
application/json:
schema:
type: object
description: The OpenAPI 3.0 specification document as a JSON object.
application/yaml:
schema:
type: string
description: The OpenAPI 3.0 specification document as a YAML string.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
digestAuth:
type: http
scheme: digest
description: >-
HTTP Digest Authentication using a TiDB Cloud organization API public key
as the username and private key as the password. Keys are generated in
the TiDB Cloud console under Organization Settings > API Keys.
parameters:
dataAppId:
name: dataAppId
in: path
description: The unique identifier of the Data App.
required: true
schema:
type: string
clusterId:
name: clusterId
in: path
description: The unique identifier of the TiDB Cloud cluster used as a data source.
required: true
schema:
type: string
pageSize:
name: pageSize
in: query
description: Maximum number of results to return per page. Default is 100, maximum is 100.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
pageToken:
name: pageToken
in: query
description: Pagination token returned from a previous list request to retrieve the next page.
required: false
schema:
type: string
responses:
BadRequest:
description: The request body or parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Authentication failed. Check your API key credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimitExceeded:
description: Rate limit exceeded. The API allows 100 requests per minute.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
DataApp:
type: object
description: A TiDB Cloud Data App containing custom SQL-backed API endpoints.
properties:
dataAppId:
type: string
description: The unique identifier of the Data App.
displayName:
type: string
description: The human-readable display name of the Data App.
description:
type: string
description: A description of the Data App's purpose.
region:
type: string
description: The cloud region where this Data App is deployed.
createTime:
type: string
format: date-time
description: The timestamp when the Data App was created.
updateTime:
type: string
format: date-time
description: The timestamp when the Data App was last modified.
CreateDataAppRequest:
type: object
description: Request body for creating a new Data App.
required:
- displayName
properties:
displayName:
type: string
description: The display name for the new Data App.
description:
type: string
description: An optional description of the Data App.
clusterId:
type: string
description: An optional cluster ID to link as the initial data source.
UpdateDataAppRequest:
type: object
description: Request body for updating an existing Data App.
properties:
displayName:
type: string
description: The new display name for the Data App.
description:
type: string
description: The new description for the Data App.
ListDataAppsResponse:
type: object
description: Paginated list of Data Apps.
properties:
dataApps:
type: array
description: The list of Data App objects on this page.
items:
$ref: '#/components/schemas/DataApp'
nextPageToken:
type: string
description: Token to retrieve the next page of results.
DataSource:
type: object
description: A TiDB Cloud cluster linked as a data source within a Data App.
properties:
clusterId:
type: string
description: The unique identifier of the linked cluster.
clusterName:
type: string
description: The display name of the linked cluster.
clusterType:
type: string
description: The type of cluster (SERVERLESS or DEDICATED).
CreateDataSourceRequest:
type: object
description: Request body for linking a cluster as a data source.
required:
- clusterId
properties:
clusterId:
type: string
description: The unique identifier of the TiDB Cloud cluster to link.
ListDataSourcesResponse:
type: object
description: List of data sources for a Data App.
properties:
dataSources:
type: array
description: The list of linked data source objects.
items:
$ref: '#/components/schemas/DataSource'
Endpoint:
type: object
description: A custom SQL-backed API endpoint within a Data App.
properties:
name:
type: string
description: The resource name of the endpoint.
displayName:
type: string
description: The human-readable display name for the endpoint.
description:
type: string
description: A description of what the endpoint does.
path:
type: string
description: The URL path for the endpoint (e.g., /users/{id}).
method:
type: string
description: The HTTP method for the endpoint.
enum:
- GET
- POST
- PUT
- DELETE
clusterId:
type: string
description: The ID of the cluster this endpoint runs queries against.
sqlTemplate:
type: string
description: The SQL template executed when the endpoint is called. Supports parameter substitution.
tag:
type: string
description: A label for grouping related endpoints.
settings:
$ref: '#/components/schemas/EndpointSettings'
params:
type: array
description: The list of parameters accepted by this endpoint.
items:
$ref: '#/components/schemas/EndpointParameter'
EndpointSettings:
type: object
description: Configuration settings for an endpoint's behavior.
properties:
timeout:
type: integer
description: The maximum execution time in milliseconds before the endpoint returns a timeout error.
rowLimit:
type: integer
description: The maximum number of rows returned by a single endpoint call.
cacheEnabled:
type: boolean
description: Whether response caching is enabled for this endpoint.
cacheTtl:
type: integer
description: The time-to-live for cached responses in seconds.
paginationEnabled:
type: boolean
description: Whether cursor-based pagination is enabled for this endpoint.
EndpointParameter:
type: object
description: A parameter definition for a Data App endpoint.
properties:
name:
type: string
description: The parameter name as referenced in the SQL template.
type:
type: string
description: The data type of the parameter.
enum:
- STRING
- INTEGER
- NUMBER
- BOOLEAN
- ARRAY
required:
type: boolean
description: Whether this parameter must be provided when calling the endpoint.
defaultValue:
type: string
description: The default value used when the parameter is not provided.
CreateEndpointRequest:
type: object
description: Request body for creating a new endpoint within a Data App.
required:
- displayName
- path
- method
- clusterId
- sqlTemplate
properties:
displayName:
type: string
description: The display name for the new endpoint.
description:
type: string
description: An optional description of the endpoint.
path:
type: string
description: The URL path for the endpoint.
method:
type: string
description: The HTTP method for the endpoint.
enum:
- GET
- POST
- PUT
- DELETE
clusterId:
type: string
description: The ID of the cluster this endpoint queries.
sqlTemplate:
type: string
description: The SQL template to execute when the endpoint is called.
tag:
type: string
description: An optional label for grouping the endpoint.
settings:
$ref: '#/components/schemas/EndpointSettings'
params:
type: array
description: Parameter definitions for this endpoint.
items:
$ref: '#/components/schemas/EndpointParameter'
ListEndpointsResponse:
type: object
description: Paginated list of endpoints in a Data App.
properties:
endpoints:
type: array
description: The list of endpoint objects on this page.
items:
$ref: '#/components/schemas/Endpoint'
nextPageToken:
type: string
description: Token to retrieve the next page of results.
DataAppApiKey:
type: object
description: An API key scoped to a specific Data App for authenticating endpoint calls.
properties:
apiKeyId:
type: string
description: The unique identifier of the Data App API key.
publicKey:
type: string
description: The public key used as the username in Digest Authentication.
privateKey:
type: string
description: The private key used as the password. Only returned at creation time.
description:
type: string
description: A human-readable description for the API key.
role:
type: string
description: The permission role assigned to the key.
enum:
- READ_ONLY
- READ_AND_WRITE
rateLimitRpm:
type: integer
description: The rate limit in requests per minute for this key.
minimum: 1
maximum: 1000
CreateDataAppApiKeyRequest:
type: object
description: Request body for creating a new Data App API key.
required:
- role
properties:
description:
type: string
description: A description for the new API key.
role:
type: string
description: The permission role for the API key.
enum:
- READ_ONLY
- READ_AND_WRITE
rateLimitRpm:
type: integer
description: Rate limit in requests per minute.
minimum: 1
maximum: 1000
ListDataAppApiKeysResponse:
type: object
description: List of API keys for a Data App.
properties:
apiKeys:
type: array
description: The list of Data App API key objects.
items:
$ref: '#/components/schemas/DataAppApiKey'
nextPageToken:
type: string
description: Token to retrieve the next page of results.
Deployment:
type: object
description: A versioned deployment of a Data App.
properties:
deploymentId:
type: string
description: The unique identifier of this deployment.
dataAppId:
type: string
description: The ID of the Data App that was deployed.
status:
type: string
description: The status of the deployment.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
createTime:
type: string
format: date-time
description: The timestamp when the deployment was created.
ListDeploymentsResponse:
type: object
description: Paginated list of deployments for a Data App.
properties:
deployments:
type: array
description: The list of deployment objects on this page.
items:
$ref: '#/components/schemas/Deployment'
nextPageToken:
type: string
description: Token to retrieve the next page of results.
ErrorResponse:
type: object
description: Standard error response returned when an API request fails.
properties:
code:
type: integer
description: The HTTP status code of the error.
status:
type: string
description: The error status string.
error:
type: string
description: A machine-readable error code identifier.
message:
type: string
description: A human-readable error message describing the failure.