tidb Data Sources API

openapi: 3.2.0
info:
  title: TiDB Cloud Data Service Data Sources 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/
servers:
- url: https://dataservice.tidbapi.com/v1beta1
  description: Data Service Management API Server
security:
- digestAuth: []
tags:
- name: Data Sources
  description: Operations for linking and managing TiDB Cloud clusters as data sources within a Data App.
paths:
  /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'
components:
  schemas:
    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.
    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.
    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'
    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).
  parameters:
    clusterId:
      name: clusterId
      in: path
      description: The unique identifier of the TiDB Cloud cluster used as a data source.
      required: true
      schema:
        type: string
    dataAppId:
      name: dataAppId
      in: path
      description: The unique identifier of the Data App.
      required: true
      schema:
        type: string
  responses:
    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'
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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.
externalDocs:
  description: TiDB Cloud Data Service Overview
  url: https://docs.pingcap.com/tidbcloud/data-service-overview/