TiDB Cloud Chat2Query API

openapi: 3.1.0
info:
  title: TiDB Cloud Chat2Query API
  description: >-
    The TiDB Cloud Chat2Query API is an AI-powered interface that enables
    developers to generate and execute SQL statements against TiDB Cloud clusters
    using natural language instructions. It is exposed as a special Data App
    within TiDB Cloud, authenticated via API keys scoped to the Chat2Query Data
    App. The API provides endpoints for generating data summaries of database
    schemas, translating natural language prompts into SQL via the v2 and v3
    chat2data endpoints, refining existing queries, managing multi-round chat
    sessions, and suggesting questions for data exploration. It is intended for
    building AI-assisted data exploration tools, reporting interfaces, and
    applications that need to query structured data without requiring users to
    write SQL directly. The API uses HTTP Digest Authentication and is rate
    limited to 100 requests per day per Data App.
  version: v3
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/use-chat2query-api/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
externalDocs:
  description: TiDB Cloud Chat2Query API Reference
  url: https://docs.pingcap.com/tidbcloud/use-chat2query-api/
servers:
  - url: https://data.tidbcloud.com/api/v1beta/app/{dataAppId}/endpoint
    description: Chat2Query Data App Endpoint Server
    variables:
      dataAppId:
        description: The Chat2Query Data App ID assigned by TiDB Cloud.
        default: dataapp_default
tags:
  - name: Chat2Data
    description: Operations for translating natural language questions into SQL and executing them against TiDB Cloud clusters.
  - name: Data Summaries
    description: Operations for generating and managing AI summaries of database schemas used as context for SQL generation.
  - name: Sessions
    description: Operations for creating and managing multi-round conversational chat sessions.
  - name: SQL Refinement
    description: Operations for refining and improving previously generated SQL queries.
security:
  - digestAuth: []
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'
  /v3/chat2data:
    post:
      operationId: generateAndExecuteSql
      summary: Generate and execute SQL from natural language
      description: >-
        Translates a natural language question into a SQL statement and executes
        it against the specified TiDB Cloud cluster and database. The AI model
        uses the data summary to understand schema context. Supports two generation
        modes: direct for simple queries, and auto_breakdown for complex questions
        that benefit from decomposed multi-step query plans.
      tags:
        - Chat2Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Chat2DataRequest'
      responses:
        '200':
          description: SQL generated and executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat2DataResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v3/refineSql:
    post:
      operationId: refineSql
      summary: Refine a SQL query
      description: >-
        Takes a previously generated SQL query and a refinement instruction, then
        produces an improved SQL statement. Use this endpoint to iteratively
        improve query accuracy based on user feedback without starting a new
        query generation from scratch.
      tags:
        - SQL Refinement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefineSqlRequest'
      responses:
        '200':
          description: SQL refined successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat2DataResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v3/suggestQuestions:
    post:
      operationId: suggestQuestions
      summary: Suggest questions for a database
      description: >-
        Returns a list of suggested natural language questions that are relevant
        and answerable given the schema of the specified database. Use this
        endpoint to populate question suggestion UI in data exploration tools.
      tags:
        - Chat2Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestQuestionsRequest'
      responses:
        '200':
          description: Question suggestions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestQuestionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v3/sessions:
    post:
      operationId: createChatSession
      summary: Create a chat session
      description: >-
        Creates a new multi-round conversational chat session. Sessions maintain
        conversation context across multiple chat2data calls, enabling follow-up
        questions that reference prior results. Use the returned session ID in
        subsequent chat2data requests to continue the conversation.
      tags:
        - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: Chat session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /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'
  /v2/chat2data:
    post:
      operationId: generateAndExecuteSqlV2
      summary: Generate and execute SQL from natural language (v2)
      description: >-
        Translates a natural language question into SQL and executes it using
        the v2 Chat2Query API. This is an asynchronous operation that returns
        a job ID. Poll the /v2/jobs/{job_id} endpoint to retrieve results.
        The v3 endpoint is recommended for new integrations as it returns
        results synchronously and supports more features.
      tags:
        - Chat2Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Chat2DataRequest'
      responses:
        '200':
          description: SQL generation job created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v2/jobs/{job_id}:
    get:
      operationId: getJobStatus
      summary: Get job status
      description: >-
        Returns the current status and result of an asynchronous Chat2Query v2
        job. Poll this endpoint after calling the v2 chat2data endpoint until the
        job status is DONE or FAILED. The query results are included in the
        response once the job is complete.
      tags:
        - Chat2Data
      parameters:
        - name: job_id
          in: path
          description: The unique identifier of the Chat2Query job.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: >-
        HTTP Digest Authentication using a Chat2Query Data App API public key
        as the username and private key as the password. Keys are generated
        within the Chat2Query Data App in the TiDB Cloud console.
  parameters:
    dataSummaryId:
      name: data_summary_id
      in: path
      description: The unique identifier of the data summary.
      required: true
      schema:
        type: integer
  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'
  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.
    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'
    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
    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'
    Chat2DataRequest:
      type: object
      description: Request body for generating and executing a SQL query from natural language.
      required:
        - cluster_id
        - database
        - question
      properties:
        cluster_id:
          type: string
          description: The ID of the TiDB Cloud cluster to run the SQL query against.
        database:
          type: string
          description: The database within the cluster to query.
        data_summary_id:
          type: integer
          description: The ID of a previously generated data summary to use as schema context.
        question:
          type: string
          description: The natural language question to translate into SQL and execute.
        sql_generate_mode:
          type: string
          description: The SQL generation strategy to use.
          enum:
            - direct
            - auto_breakdown
          default: direct
        session_id:
          type: string
          description: The session ID for multi-round conversational queries.
    Chat2DataResponse:
      type: object
      description: API response wrapper for a Chat2Data 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/Chat2DataResult'
    Chat2DataResult:
      type: object
      description: The result of a Chat2Data SQL generation and execution.
      properties:
        question_id:
          type: string
          description: A unique identifier for this question and result pair.
        sql:
          type: string
          description: The SQL statement that was generated from the natural language question.
        rows:
          type: array
          description: The query result rows returned by executing the generated SQL.
          items:
            type: object
            additionalProperties: true
        columns:
          type: array
          description: The column definitions for the query result.
          items:
            $ref: '#/components/schemas/ColumnDefinition'
    ColumnDefinition:
      type: object
      description: A column definition in a query result set.
      properties:
        col:
          type: string
          description: The column name.
        data_type:
          type: string
          description: The SQL data type of the column.
        nullable:
          type: boolean
          description: Whether the column can contain NULL values.
    RefineSqlRequest:
      type: object
      description: Request body for refining a previously generated SQL query.
      required:
        - cluster_id
        - database
        - question
        - sql
        - task
      properties:
        cluster_id:
          type: string
          description: The ID of the TiDB Cloud cluster.
        database:
          type: string
          description: The database within the cluster.
        question:
          type: string
          description: The original natural language question that produced the SQL.
        sql:
          type: string
          description: The SQL query to be refined.
        task:
          type: string
          description: A description of how to refine the SQL query.
    SuggestQuestionsRequest:
      type: object
      description: Request body for generating question suggestions for a database.
      required:
        - cluster_id
        - database
      properties:
        cluster_id:
          type: string
          description: The ID of the TiDB Cloud cluster.
        database:
          type: string
          description: The database to generate question suggestions for.
    SuggestQuestionsResponse:
      type: object
      description: API response wrapper for question suggestions.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          type: object
          properties:
            questions:
              type: array
              description: A list of suggested natural language questions for the database.
              items:
                type: string
    CreateSessionRequest:
      type: object
      description: Request body for creating a multi-round chat session.
      required:
        - cluster_id
        - database
      properties:
        cluster_id:
          type: string
          description: The ID of the TiDB Cloud cluster for this session.
        database:
          type: string
          description: The database to use for this chat session.
    ChatSession:
      type: object
      description: A multi-round conversational chat session.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          type: object
          properties:
            session_id:
              type: string
              description: The unique session identifier to use in subsequent chat2data requests.
    JobResponse:
      type: object
      description: Response for asynchronous v2 Chat2Query job creation.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          type: object
          properties:
            job_id:
              type: string
              description: The unique identifier for polling the job status.
    JobStatusResponse:
      type: object
      description: Status and result of an asynchronous Chat2Query v2 job.
      properties:
        code:
          type: integer
          description: The response code. 200 indicates success.
        msg:
          type: string
          description: A message describing the result.
        result:
          type: object
          properties:
            job_id:
              type: string
              description: The job identifier.
            status:
              type: string
              description: The current status of the job.
              enum:
                - RUNNING
                - DONE
                - FAILED
            data:
              $ref: '#/components/schemas/Chat2DataResult'
    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.