PingCAP Data App API

openapi: 3.2.0
info:
  title: TiDB Cloud Data Service OPEN Data App API
  description: '# Overview


    The TiDB Cloud Data Service API provides a RESTful interface for programmatically managing administrative objects within the TiDB Cloud Data Service.'
  version: v1beta1
servers:
- url: https://dataservice.tidbapi.com
tags:
- name: Data App
  description: Create, get, update, delete, and list Data Apps.
paths:
  /v1beta1/dataApps:
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps?projectId={projectId}&pageSize=5'"
      summary: List all Data Apps in a project
      operationId: DataApp_ListDataApps
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListDataAppsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: projectId
        description: The ID of the project that the Data App belongs to. You can get the project ID from the response of [List all accessible projects](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/ListProjects).
        in: query
        required: true
        schema:
          type: string
      - name: pageSize
        description: The maximum number of items to return. If it is not set or set to `0`, the default value `100` will be used.
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 100
          minimum: 1
      - name: pageToken
        description: The identifier of the current page, used to retrieve the next page of results. You can get this value from the `nextPageToken` field in the previous response. To access the first page of data, omit this field.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Data App
    post:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"version\": \"1.0.0\", \n    \"projectId\": \"{projectId}\", \n    \"clusterIds\": [\n         \"{clusterIds}\"\n     ], \n     \"appType\": \"DATAAPP\", \n     \"displayName\": \"app-01\", \n     \"description\": \"A new data app\" \n  }'"
      summary: Create a Data App
      operationId: DataApp_CreateDataApp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1DataAppRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      tags:
      - Data App
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1DataApp'
        description: DataApp
        required: true
  /v1beta1/dataApps/{dataAppId}/systemEndpointConfig:
    get:
      summary: List all system endpoints in a Data App
      description: 'TiDB Cloud Data Service provides an endpoint library with predefined system endpoints that you can directly add to your Data App, reducing the effort in your endpoint development.


        For example, the `POST:/system/query` system endpoint enables you to execute any SQL statement by simply passing the statement in the predefined `sql` parameter. This endpoint facilitates the immediate execution of SQL queries, enhancing flexibility and efficiency.'
      operationId: DataAppsService_GetSystemEndpointConfig
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1SystemEndpointConfigRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/systemEndpointConfig'"
      tags:
      - Data App
    patch:
      summary: Update the configuration of system endpoints
      description: With this endpoint, you can enable or disable the system endpoints in a Data App.
      operationId: DataAppsService_UpdateSystemEndpointConfig
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1SystemEndpointConfigRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request PATCH \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/systemEndpointConfig' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"items\": {\n      \"type\": \"system-data\", \n      \"key\": \"POST:/system/query\", \n      \"enabled\": true \n    }\n  }'"
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/v1beta1SystemEndpointConfigItem'
                  description: The configuration items of system endpoints in a Data App.
                  required:
                  - items
              title: System Endpoint Config
              required:
              - items
        description: 'To update the configuration of system endpoints in a Data App, specify the following fields as needed:'
        required: true
  /v1beta1/dataApps/{dataAppId}/chat2querySettings:
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/chat2querySettings'"
      summary: Get Chat2Query Data App settings by ID
      description: With this endpoint, you can get the settings of a Chat2Query Data App, such as `name`, `llmApiKey`, `languageCode`, and `llmModel`. To get basic information, such as `version`, `projectId`, and `clusterIds`, use the Get a Data App by ID endpoint instead.
      operationId: DataApp_GetChat2QuerySettings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Chat2QuerySettingsRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
    patch:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request PATCH \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/chat2querySettings' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"llmModel\": \"gpt-4\", \n    \"llmApiKey\": \"sk-projxxxx\", \n    \"languageCode\": \"English\" \n  }'"
      summary: Update Chat2Query Data App settings by ID
      description: With this endpoint, you can update the `llmApiKey`, `languageCode`, or `llmModel` settings of a Chat2Query Data App. To update the version, name, or description, use the Update a Data App endpoint instead.
      operationId: DataApp_UpdateChat2QuerySettings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Chat2QuerySettingsRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                llmApiKey:
                  type: string
                  description: The access key required to use your large language model (LLM) service. Leaving this blank limits you to 100 queries per day. To bypass the query limit, specify your access key of [OpenAI models](https://platform.openai.com/docs/models) in the `sk-xxxx` format.
                  required:
                  - llmApiKey
                languageCode:
                  type: string
                  description: 'The language to use for this Chat2Query Data App. Value options: `"English"` or `"Chinese"`.'
                  required:
                  - languageCode
                llmModel:
                  type: string
                  description: 'The LLM model to use for this Chat2Query Data App.

                    **Note:** You cannot use the `gpt-4` or `gpt-4o` model without a valid `llmApiKey`. Value options: `gpt-4`, `gpt-4o`, `gpt-4o-mini`.'
                  required:
                  - llmModel
              title: Define your fields as needed for updating a Chat2Query App Settings
        description: 'To update the settings of a Chat2Query App, specify the following fields as needed:'
        required: true
  /v1beta1/dataApps/{dataAppId}:
    patch:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request PATCH \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"version\": \"1.0.1\", \n    \"displayName\": \"app-02\", \n    \"description\": \"Update a data app\" \n  }'"
      summary: Update a Data App
      description: With this endpoint, you can update the `version`, `name`, or `description` of a Data App. To update the `llmApiKey`, `languageCode`, or `llmModel` settings of a Chat2Query App, use the Update Chat2Query App settings by Data App ID endpoint instead.
      operationId: DataApp_UpdateDataApp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1DataAppRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: The user-defined version number of the Data App, in the format of `x.x.x`.
                  pattern: ^[1-9]\.[0-9]\.[0-9]$
                  example: 1.0.0
                  default: 1.0.0
                displayName:
                  type: string
                  description: The user-defined name of the Data App.
                  maxLength: 32
                  minLength: 1
                description:
                  type: string
                  description: The user-defined description of the Data App.
                  maxLength: 0
                  minLength: 1000
              title: Define your fields as needed for updating a Data App
        description: 'To update a Data App, specify the following fields as needed:'
        required: true
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}'"
      summary: Get a Data App by ID
      description: With this endpoint, you can get the basic information of a Data App, such as `name`, `version`, `projectId`, and `clusterIds`. To get the `llmApiKey`, `languageCode`, and `llmModel` of a Chat2Query Data App, use the Get Chat2Query Data App settings by ID endpoint instead.
      operationId: DataApp_GetDataApp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1DataAppRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
    delete:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request DELETE \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}'"
      summary: Delete a Data App
      operationId: DataApp_DeleteDataApp
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        default:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data App
components:
  schemas:
    v1beta1Chat2QuerySettingsRes:
      type: object
      properties:
        name:
          type: string
          description: The unique identifier for the Chat2Query Data App settings, which is generated by the API and follows the format `dataApps/{data_app}/chat2querySettings`.
        llmApiKey:
          type: string
          description: The access key required to use your large language model (LLM) service.
          required:
          - llmApiKey
        languageCode:
          type: string
          description: The language to use for this Chat2Query Data App.
          required:
          - languageCode
        llmModel:
          type: string
          description: The LLM model to use for this Chat2Query Data App.
          required:
          - llmModel
      required:
      - llmApiKey
      - languageCode
      - llmModel
    v1beta1DataApp:
      type: object
      properties:
        dataAppId:
          type: string
          description: The ID of the Data App.
          readOnly: true
        name:
          type: string
          description: The unique identifier for the Data App, which is generated by the API and follows the format `dataApps/{dataAppId}`
          readOnly: true
        projectId:
          type: string
          description: The ID of the project that the Data App belongs to. You can get the project ID from the response of [List all accessible projects](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/ListProjects).
          required:
          - projectId
        clusterIds:
          type: array
          items:
            type: string
          description: The IDs of the clusters that the Data App's data source is linked to.
        appType:
          $ref: '#/components/schemas/v1beta1DataAppType'
          description: "The type of the Data App.\n - `DATAAPP`: standard Data APP\n - `CHAT2QUERY`: Chat2Query Data App"
        version:
          type: string
          description: The user-defined version number of the Data App, in the format of `x.x.x`.
          pattern: ^[1-9]\.[0-9]\.[0-9]$
          example: 1.0.0
          default: 1.0.0
          required:
          - version
        displayName:
          type: string
          description: The user-defined name of the Data App.
          minLength: 1
          maxLength: 32
          required:
          - displayName
        description:
          type: string
          description: The user-defined description of the Data App.
          minLength: 0
          maxLength: 1000
          required:
          - description
        createdAt:
          type: string
          title: 'The timestamp when the Data App was created. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
          readOnly: true
        updatedAt:
          type: string
          title: 'The timestamp when the Data App was last updated. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
          readOnly: true
    v1beta1DataAppRes:
      type: object
      properties:
        dataAppId:
          type: string
          description: The ID of the Data App.
          readOnly: true
        name:
          type: string
          description: The unique identifier for the Data App, which is generated by the API and follows the format `dataApps/{data_app_id}`.
        version:
          type: string
          description: The user-defined version number of the Data App.
          default: 1.0.0
        projectId:
          type: string
          description: The ID of the project that the Data App belongs to.
        clusterIds:
          type: array
          items:
            type: string
          description: The IDs of the clusters that the Data App's data source is linked to.
        appType:
          $ref: '#/components/schemas/v1beta1DataAppType'
          description: "The type of the Data App.\n - `DATAAPP`: standard Data APP\n - `CHAT2QUERY`: Chat2Query Data App"
        displayName:
          type: string
          description: The user-defined name of the Data App.
        description:
          type: string
          description: The user-defined description of the Data App.
        createdAt:
          type: string
          description: 'The timestamp when the Data App was created. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
        updatedAt:
          type: string
          description: 'The timestamp when the Data App was last updated. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
    v1beta1DataAppType:
      type: string
      enum:
      - DATAAPP
      - CHAT2QUERY
      description: "The type of the Data App.\n - `DATAAPP`: standard Data APP\n - `CHAT2QUERY`: Chat2Query Data App"
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v1beta1ListDataAppsResponse:
      type: object
      properties:
        dataApps:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1DataAppRes'
          description: The items of Data Apps in the project.
        nextPageToken:
          type: string
          description: The token to retrieve the next page of results.
      title: Response for ListDataApps
    v1beta1SystemEndpointConfigItem:
      type: object
      properties:
        type:
          type: string
          description: The type of the system endpoint.
          example: system-data
          required:
          - type
        key:
          type: string
          description: 'The key of the system endpoint, combining the HTTP method and endpoint path. For example: `"POST:/system/query"`.'
          example: POST:/system/query
          required:
          - key
        enabled:
          type: boolean
          description: Controls whether to enable the system endpoint in a Data App.
          required:
          - enabled
      required:
      - type
      - key
      - enabled
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    v1beta1SystemEndpointConfigRes:
      type: object
      properties:
        name:
          type: string
          description: The unique identifier for the system endpoint configurations in a Data App, which is generated by the API and follows the format `dataApps/{data_app}/systemEndpointConfig`.
        items:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1SystemEndpointConfigItem'
          description: The configuration items of system endpoints in a Data App.
          required:
          - items
      title: Response for UpdateSystemEndpointConfig
      required:
      - items
x-tagGroups:
- name: Endpoints
  tags:
  - Data App
  - Data Source
  - Endpoint
  - Deployment
  - Data API Key
  - OpenAPI Specification