tidb-cloud-data-service-openapi.yml

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.