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.
  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'
    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.
    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.
    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'
    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.
  responses:
    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'
    Unauthorized:
      description: Authentication failed. Check your Chat2Query API key credentials.
      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/