openapi: 3.2.0
info:
  title: TiDB Cloud Chat2Query Sessions 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: Sessions
  description: Operations for creating and managing multi-round conversational chat sessions.
paths:
  /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'
components:
  schemas:
    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.
    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.
    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.
  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/