openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Data Summaries 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 Summaries
  description: Operations for generating and managing AI summaries of database schemas used as context for SQL generation.
paths:
  /v3/dataSummaries:
    get:
      operationId: listDataSummaries
      summary: List data summaries
      description: Returns all AI-generated data summaries for the Chat2Query Data App. A data summary captures the schema structure and statistical profile of a database, providing context that the AI uses to generate more accurate SQL statements. Summaries must be created before calling the chat2data endpoint with a data_summary_id.
      tags:
      - Data Summaries
      responses:
        '200':
          description: List of data summaries retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataSummariesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    post:
      operationId: createDataSummary
      summary: Create a data summary
      description: Generates an AI-powered summary of the specified database schema on a linked TiDB Cloud cluster. The summary analyzes table structures, relationships, and data distributions to provide context for subsequent SQL generation. Set reuse to true to return an existing summary if one already exists for this database.
      tags:
      - Data Summaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataSummaryRequest'
      responses:
        '200':
          description: Data summary creation initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v3/dataSummaries/{data_summary_id}:
    get:
      operationId: getDataSummary
      summary: Get a data summary
      description: Returns the details and current generation status of a specific data summary by its ID. Data summary generation is asynchronous; poll this endpoint until the status is DONE before using the summary_id in a chat2data request.
      tags:
      - Data Summaries
      parameters:
      - $ref: '#/components/parameters/dataSummaryId'
      responses:
        '200':
          description: Data summary retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDataSummary
      summary: Update a data summary
      description: Regenerates or updates an existing data summary for a database. Use this endpoint to refresh a summary after significant schema or data changes to keep AI-generated SQL accurate.
      tags:
      - Data Summaries
      parameters:
      - $ref: '#/components/parameters/dataSummaryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataSummaryRequest'
      responses:
        '200':
          description: Data summary updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/dataSummaries:
    post:
      operationId: createDataSummaryV2
      summary: Create a data summary (v2)
      description: Generates a data summary of the specified database schema using the v2 Chat2Query API. This is the v2 version of the data summary endpoint. The v3 endpoint is recommended for new integrations as it supports additional features including knowledge bases and session management.
      tags:
      - Data Summaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataSummaryRequest'
      responses:
        '200':
          description: Data summary creation initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed. Check your Chat2Query 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 Chat2Query API allows 100 requests per day per Data App. Contact TiDB Cloud support to request a higher limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    dataSummaryId:
      name: data_summary_id
      in: path
      description: The unique identifier of the data summary.
      required: true
      schema:
        type: integer
  schemas:
    CreateDataSummaryRequest:
      type: object
      description: Request body for creating a new database schema data summary.
      required:
      - cluster_id
      - database
      properties:
        cluster_id:
          type: string
          description: The ID of the TiDB Cloud cluster whose database will be summarized.
        database:
          type: string
          description: The name of the database to generate a summary for.
        description:
          type: string
          description: An optional human-readable description for this data summary.
        reuse:
          type: boolean
          description: If true, returns an existing summary for this database instead of generating a new one.
    ListDataSummariesResponse:
      type: object
      description: API response wrapper for listing data summaries.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          type: array
          description: The list of data summary objects.
          items:
            $ref: '#/components/schemas/DataSummary'
    DataSummaryResponse:
      type: object
      description: API response wrapper for a data summary operation.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          $ref: '#/components/schemas/DataSummary'
    ErrorResponse:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: The error code.
        msg:
          type: string
          description: A human-readable error message describing the failure.
    DataSummary:
      type: object
      description: An AI-generated summary of a database schema.
      properties:
        data_summary_id:
          type: integer
          description: The unique identifier of the data summary.
        cluster_id:
          type: string
          description: The ID of the cluster whose database was summarized.
        database:
          type: string
          description: The name of the summarized database.
        status:
          type: string
          description: The generation status of the data summary.
          enum:
          - RUNNING
          - DONE
          - FAILED
  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/