tidb Chat2Data API

openapi: 3.2.0
info:
  title: TiDB Cloud Chat2Query Chat2 Data 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: Chat2Data
  description: Operations for translating natural language questions into SQL and executing them against TiDB Cloud clusters.
paths:
  /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/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'
  /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:
  schemas:
    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'
    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.
    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.
    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.
    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.
    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
    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'
    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.
  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'
    NotFound:
      description: The requested resource was not found.
      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/