openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Chat2Data 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: 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:
    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
    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.
    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.
    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.
    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.
    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.
    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'
    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'
    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'
  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/