tidb SQL Refinement API

openapi: 3.2.0
info:
  title: TiDB Cloud Chat2Query SQL Refinement 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/
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
security:
- digestAuth: []
tags:
- name: SQL Refinement
  description: Operations for refining and improving previously generated SQL queries.
paths:
  /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'
components:
  schemas:
    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'
    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.
    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.
    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.
    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'
  responses:
    Unauthorized:
      description: Authentication failed. Check your Chat2Query API key credentials.
      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'
    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 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.
externalDocs:
  description: TiDB Cloud Chat2Query API Reference
  url: https://docs.pingcap.com/tidbcloud/use-chat2query-api/