TiDB Cloud Data Service API (v1beta1)

{
  "swagger": "2.0",
  "info": {
    "title": "TiDB Cloud Data Service OPENAPI",
    "description": "# Overview\n\nThe TiDB Cloud Data Service API provides a [RESTful interface](https://en.wikipedia.org/wiki/Representational_state_transfer) for programmatically managing administrative objects within the [TiDB Cloud Data Service](https://docs.pingcap.com/tidbcloud/data-service-overview). Through this API, you can manage the following resources automatically and efficiently:\n\n* **Data App**: a collection of endpoints that you can use to access data for a specific application.\n* **Data Source**: clusters linked to Data Apps for data manipulation and retrieval.\n* **Endpoint**: a web API that you can customize to execute SQL statements. You can specify parameters for the SQL statements, such as the value used in the `WHERE` clause. When a client calls an endpoint and provides values for the parameters in a request URL, the endpoint executes the SQL statement with the provided parameters and returns the results as part of the HTTP response.\n* **Deployment**: the process of deploying Data Apps.\n* **Data API Key**: used for secure endpoint access. This key is used to access data in the TiDB Cloud clusters, whereas the TiDB Cloud organization API key is used to manage resources such as projects, clusters, Data Apps, and endpoints.\n* **OpenAPI Specification**: Data Service supports generating the OpenAPI Specification 3.0 for each Data App, which enables you to interact with your endpoints in a standardized format. You can use this specification to generate standardized OpenAPI documentation, client SDKs, and server stubs.\n\n# Get Started\n\nThis guide helps you make your first API call to TiDB Cloud Data Service API. You'll learn how to authenticate a request, build a request, and interpret the response. The [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint is used in this guide as an example.\n\n## Prerequisites\n\nTo complete this guide, you need to perform the following tasks:\n\n- Create a [TiDB Cloud account](https://tidbcloud.com/free-trial)\n- Install [curl](https://curl.se/)\n\n## Step 1. Create an organization API key\n\nTo create an organization API key, log in to your TiDB Cloud console. Navigate to the [**API Keys**](https://tidbcloud.com/org-settings/api-keys) page of your organization, and create an API key.\n\nAn organization API key contains a public key and a private key. Copy and save them in a secure location. You will need to use the API key later in this guide.\n\nFor more details about creating an organization API key, refer to [API Key Management](#section/Authentication/API-Key-Management).\n\n## Step 2. Make your first API call\n\n### Build an API call\n\nTiDB Cloud Data Service API call consists of the following components:\n\n- **A host.** The host for TiDB Cloud Data Service API is <https://dataservice.tidbapi.com>.\n- **An organization API Key**. The public key and the private key are required for authentication.\n- **A request.** When submitting data to a resource via `POST`, `PATCH`, or `PUT`, you must submit your payload in JSON.\n\nIn this guide, you call the [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint. For a detailed description of the endpoint, see the [API reference](#tag/Data-App/operation/DataApp_ListDataApps).\n\n### Call an API endpoint\n\nTo get all Data Apps in your project, run the following command in your terminal. Replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_PROJECT_ID` with your actual values. To get the project ID, you can call the [List all accessible projects](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/ListProjects) endpoint.\n\n```bash\ncurl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps?projectId=YOUR_PROJECT_ID'\n```\n\n## Step 3. Check the response\n\nAfter making the API call, if the status code in response is `200` and you see details about all the Data Apps in your project, your request is successful. Here is an example of a successful response.\n\n```log\n{\n  \"dataApps\": [\n    {\n      \"dataAppId\": \"{data_app_id}\",\n      \"name\": \"dataApps/{data_app_id}\",\n      \"version\": \"\",\n      \"projectId\": \"{project_id}\",\n      \"clusterIds\": [],\n      \"appType\": \"DATAAPP\",\n      \"displayName\": \"New Data App\",\n      \"description\": \"\",\n      \"createdAt\": \"2023-06-03T06:52:08Z\",\n      \"updatedAt\": \"2023-06-03T06:52:08Z\"\n    },\n    {\n      \"dataAppId\": \"{data_app_id}\",\n      \"name\": \"dataApps/{data_app_id}\",\n      \"version\": \"\",\n      \"projectId\": \"{project_id}\",\n      \"clusterIds\": [],\n      \"appType\": \"CHAT2QUERY\",\n      \"displayName\": \"New App\",\n      \"description\": \"\",\n      \"createdAt\": \"2023-06-03T06:52:08Z\",\n      \"updatedAt\": \"2023-06-03T06:52:08Z\"\n    }\n  ],\n  \"nextPageToken\": \"\"\n}\n```\n\nIf your API call is not successful, you will receive a status code other than `200` and the response looks similar to the following example. To troubleshoot the failed call, you can check the `message` in the response.\n\n```log\n{\n  \"code\": 403,\n  \"message\": \"Request error, projectId not exist\",\n  \"details\": []\n}\n```\n\n# Call a Deployed Data Service Endpoint\n\nIf you have deployed a Data Service endpoint, you can call it using the Data API key. To begin, follow these steps:\n\n1. Generate a Data API key by calling the [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey) endpoint. You can run the following `curl` command and replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_DATAAPP_ID` with your actual values. Note that `YOUR_PUBLIC_KEY` and `YOUR_PRIVATE_KEY` are [organization API keys](#section/Authentication/Organization-API-key-overview).\n\n    ```bash\n    curl --digest \\\n      --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n      --request POST \\\n      --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/YOUR_DATAAPP_ID/apiKeys'\\\n      --header 'Content-Type: application/json' \\\n      --data '{\n        \"description\": \"A new API Key\",\n        \"role\": \"READ_AND_WRITE\",\n        \"rateLimitRpm\": 100\n      }'\n    ```\n\n2. Call the deployed endpoint. Suppose that you have created a `GET` endpoint named `/hello`, with the request URL as `https://data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello`. To call this endpoint, replace `YOUR_DATAAPP_PUBLIC_KEY` and `YOUR_DATAAPP_PRIVATE_KEY` with the values obtained from the response in step 1, and replace `YOUR_DATAAPP_ID` with the actual Data App ID in the following command:\n\n    ```bash\n    curl --location-trusted --digest \\\n      --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n      --request GET \\\n      --url 'https://data.tidbcloud.com/api/v1beta/app/YOUR_DATAAPP_ID/endpoint/hello'\n    ```\n    \n    For improved performance, you can call the endpoint using the regional domain name. Replace `REGION` with the specific region name to which the cluster belongs, such as `us-west-2`.\n    \n    ```bash\n    curl --digest \\\n      --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n      --request GET \\\n      --url 'https://REGION.data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello'\n    ```\n\n# Authentication\n\nThe TiDB Cloud Data Service API uses [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication). It protects your private key from being sent over the network. For more details about HTTP Digest Authentication, refer to the [IETF RFC](https://datatracker.ietf.org/doc/html/rfc7616).\n\n## Organization API key overview\n\n- The organization API key contains a public key and a private key, which act as the username and password required in the HTTP Digest Authentication. The private key only displays upon the key creation.\n- The organization API key belongs to your organization and acts as the `Organization Owner` role. You can check [permissions of owner](https://docs.pingcap.com/tidbcloud/manage-user-access#configure-member-roles).\n- You must provide the correct organization API key in every request. Otherwise, TiDB Cloud responds with a `401` error.\n\n## Organization API key management\n\n### Create an organization API key\n\nOnly the **owner** of an organization can create an organization API key.\n\nTo create an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **Create API Key**.\n4. Enter a description for your API key. The role of the API key is always `Organization Owner` currently.\n5. Click **Next**. Copy and save the public key and the private key.\n6. Make sure that you have copied and saved the private key in a secure location. The private key only displays upon the creation. After leaving this page, you will not be able to get the full private key again.\n7. Click **Done**.\n\n### View details of an organization API key\n\nTo view details of an organization API key, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. You can view the details of the API keys on the page.\n\n### Edit an organization API key\n\nOnly the **owner** of an organization can modify an organization API key.\n\nTo edit an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to change, and then click **Edit**.\n4. You can update the API key description.\n5. Click **Update**.\n\n### Delete an organization API key\n\nOnly the **owner** of an organization can delete an organization API key.\n\nTo delete an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to delete, and then click **Delete**.\n4. Click **I understand, delete it.**\n\n# Rate Limiting\n\nThe TiDB Cloud Data Service API allows up to 100 requests per minute per API key. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519) to contact our support team.\n\nEach API request returns the following headers about the limit.\n\n- `X-Ratelimit-Limit-Minute`: The number of requests allowed per minute. It is 100 currently.\n- `X-Ratelimit-Remaining-Minute`: The number of remaining requests in the current minute. When it reaches `0`, the API returns a `429` error and indicates that you exceed the rate limit.\n- `X-Ratelimit-Reset`: The time in seconds at which the current rate limit resets.\n\nIf you exceed the rate limit, an error response returns like this.\n\n```\n> HTTP/2 429\n> date: Fri, 22 Jul 2022 05:28:37 GMT\n> content-type: application/json\n> content-length: 66\n> x-ratelimit-reset: 23\n> x-ratelimit-remaining-minute: 0\n> x-ratelimit-limit-minute: 100\n> x-kong-response-latency: 2\n> server: kong/2.8.1\n\n> {\"details\":[],\"code\":49900007,\"message\":\"The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519\"}\n```\n\n# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud Data Service API.\n\n<!-- In reverse chronological order -->\n\n## 20250812\n\n- \"TiDB Cloud Serverless\" is renamed to \"TiDB Cloud Starter\".\n\n## 20240910\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for the `gpt-3.5-turbo` model and adds support for `gpt-4o` and `gpt-4o-mini` models.\n\n- \"TiDB Serverless\" is renamed to \"TiDB Cloud Serverless\".\n- \"TiDB Dedicated\" is renamed to \"TiDB Cloud Dedicated\".\n\n## 20240806\n\n- Add the [List all system endpoints in a Data App](#tag/Data-App/operation/DataAppsService_GetSystemEndpointConfig) endpoint.\n\n- Add the [Update the configuration of system endpoints](#tag/Data-App/operation/DataAppsService_UpdateSystemEndpointConfig) endpoint.\n\n## 20240716\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for Claude models.\n\n## 20240528\n\n- Initial release of the TiDB Cloud Data Service API, including the following resources and endpoints:\n\n    - Data App:\n      - [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps)\n      - [Create a Data App](#tag/Data-App/operation/DataApp_CreateDataApp)\n      - [Get Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_GetChat2QuerySettings)\n      - [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings)\n      - [Update a Data App](#tag/Data-App/operation/DataApp_UpdateDataApp)\n      - [Get a Data App by ID](#tag/Data-App/operation/DataApp_GetDataApp)\n      - [Delete a Data App](#tag/Data-App/operation/DataApp_DeleteDataApp)\n    - Data Source:\n      - [List all data sources in a Data App](#tag/Data-Source/operation/DataSource_ListDataSources)\n      - [Create a data source for a Data App](#tag/Data-Source/operation/DataSource_CreateDataSource)\n      - [Get a data source by ID](#tag/Data-Source/operation/DataSource_GetDataSource)\n      - [Delete a data source for a Data App](#tag/Data-Source/operation/DataSource_DeleteDataSource)\n    - Endpoint:\n      - [List all endpoints in a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n      - [Create an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_CreateEndpoint)\n      - [Update an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_UpdateEndpoint)\n      - [Get an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_GetEndpoint)\n      - [Delete an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_DeleteEndpoint)\n      - [Test an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_TestEndpoint)\n    - Deployment:\n      - [List all deployments for a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n      - [Create a deployment for a Data App](#tag/Deployment/operation/Deployment_CreateDeployment)\n      - [Get a deployment by ID](#tag/Deployment/operation/Deployment_GetDeployment)\n    - Data API Key:\n      - [List all API keys for a Data App](#tag/Data-API-Key/operation/APIKey_ListApiKeys)\n      - [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey)\n      - [Update an API key for a Data App](#tag/Data-API-Key/operation/APIKey_UpdateApiKey)\n      - [Get an API key by ID](#tag/Data-API-Key/operation/APIKey_GetApiKey)\n      - [Delete an API key for a Data App](#tag/Data-API-Key/operation/APIKey_DeleteApiKey)\n    - OpenAPI Specification:\n      - [Get the OpenAPI Specification of a Data App](#tag/OpenAPI-Specification/operation/APISpecification_GetApiSpec)\n",
    "version": "v1beta1"
  },
  "tags": [
    {
      "name": "Data App",
      "description": "Create, get, update, delete, and list Data Apps."
    },
    {
      "name": "Data Source",
      "description": "Create, get, delete, and list data sources of a Data App."
    },
    {
      "name": "Endpoint",
      "description": "Create, get, delete, list, and test endpoints of a Data App."
    },
    {
      "name": "Deployment",
      "description": "Create, get, and list deployments of a Data App."
    },
    {
      "name": "Data API Key",
      "description": "Create, get, update, delete, and list Data API keys of a Data App. The Data API key in Data Service is different from the key used in the [TiDB Cloud API](https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication). The Data API key is used to access data in the TiDB Cloud clusters, whereas the TiDB Cloud API key is used to manage resources such as projects, clusters, Data Apps, and endpoints."
    },
    {
      "name": "OpenAPI Specification",
      "description": "Get the OpenAPI specification of a Data App."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Endpoints",
      "tags": [
        "Data App",
        "Data Source",
        "Endpoint",
        "Deployment",
        "Data API Key",
        "OpenAPI Specification"
      ]
    }
  ],
  "host": "dataservice.tidbapi.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "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",
            "schema": {
              "$ref": "#/definitions/v1beta1ListDataAppsResponse"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "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,
            "type": "integer",
            "format": "int32",
            "default": 100,
            "minimum": 1,
            "maximum": 100
          },
          {
            "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,
            "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",
            "schema": {
              "$ref": "#/definitions/v1beta1DataAppRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "dataApp",
            "description": "DataApp",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1beta1DataApp"
            }
          }
        ],
        "tags": [
          "Data App"
        ]
      }
    },
    "/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.\n\nFor 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",
            "schema": {
              "$ref": "#/definitions/v1beta1SystemEndpointConfigRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "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",
            "schema": {
              "$ref": "#/definitions/v1beta1SystemEndpointConfigRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "type": "string"
          },
          {
            "name": "systemEndpointConfig",
            "description": "To update the configuration of system endpoints in a Data App, specify the following fields as needed:",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/v1beta1SystemEndpointConfigItem"
                  },
                  "description": "The configuration items of system endpoints in a Data App.",
                  "required": [
                    "items"
                  ]
                }
              },
              "title": "System Endpoint Config",
              "required": [
                "items"
              ]
            }
          }
        ],
        "tags": [
          "Data App"
        ]
      }
    },
    "/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](#tag/Data-App/operation/DataApp_GetDataApp) endpoint instead.",
        "operationId": "DataApp_GetChat2QuerySettings",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/v1beta1Chat2QuerySettingsRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "type": "string"
          }
        ],
        "tags": [
          "Data App",
          "Chat2Query"
        ]
      },
      "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](#tag/Data-App/operation/DataApp_UpdateDataApp) endpoint instead.",
        "operationId": "DataApp_UpdateChat2QuerySettings",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/v1beta1Chat2QuerySettingsRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "type": "string"
          },
          {
            "name": "chat2querySettings",
            "description": "To update the settings of a Chat2Query App, specify the following fields as needed:",
            "in": "body",
            "required": true,
            "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.\n**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"
            }
          }
        ],
        "tags": [
          "Data App",
          "Chat2Query"
        ]
      }
    },
    "/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](#tag/Data-App/operation/DataApp_GetChat2QuerySettings) endpoint instead.",
        "operationId": "DataApp_UpdateDataApp",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/v1beta1DataAppRes"
            }
          },
          "400": {
            "description": "Bad request",
            "schema": {
              "$ref": "#/definitions/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,
            "type": "string"
          },
          {
            "name": "dataApp",
            "description": "To update a Data App, specify the following fields as needed:",
            "in": "body",
            "required": true,
            "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"
            }
          }
        ],
        "tags": [
          "Data App"
     

# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pingcap/refs/heads/main/openapi/pingcap-tidb-cloud-data-service-v1beta1-openapi-original.json