openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Data Sources API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing 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:
  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
  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.
    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).
    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'
  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'
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud 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 API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/