Skip to content
Docs
AI-Chat
REST API

RestAPI interface document

Prerequisites

This interface document only provides AI call-related interfaces. There are two modes for AI interface calls:

The first mode is to use it with the data source management and AI data set management functions of the Chat2DB product, and Chat2DB completes the management of the database table structure.

The second mode is to manage your own database table structure by yourself, and only use Chat2DB's natural language to SQL function.

The first mode can use Chat2DB's natural language to SQL, natural language to report and other AI capabilities; the second mode cannot use the natural language to report capability, and other AI capabilities can be used.

The specific usage process is divided into the following steps. The first mode requires the execution of all the following steps, and none of them can be omitted; the second mode only requires the execution of the steps marked as (required);

Step 1: Create a data source

Create a data source in the Chat2DB product. The creation of a data source does not provide a rest interface. It must be created using the product interactive interface within the product. For specific creation methods, please refer to Create MySql Data Source (opens in a new tab)

Step 2: Create an AI dataset

After creating a data source, you need to create an AI dataset to synchronize the relevant table structure to AI. This interface does not provide a rest interface. It must be created using the product interactive interface within the product. For specific usage methods, please refer to AI dataset (opens in a new tab)

After creating the dataset, copy the dataset ID. Right-click the AI ​​dataset and select Copy dataset ID

'rest-api'

Step 3: Create an API for the Rest interface call key (required)

The API for creating ApiKey does not provide a rest interface. You must use the product interactive interface to create it within the product. Refer to the picture below and click the avatar, then click Create ApiKey. After creating ApiKey, please save it locally. The specific content of ApiKey cannot be viewed on this platform later.

'rest-api'

Step 4: Query the table matched by natural language

Get the AI ​​dataset ID created in the second step and the API key created in the third step, enter the natural language, and query the library table structure that may be used by the natural language. The specific API interface definition is as follows.

Get the matching table interface

Interface address: https://app.chat2db-ai.com/api/ai/rest/mapping_a (opens in a new tab)

Interface method: POST

Authentication method

Get the API key obtained in the second step, add Authorization to the Header in the request interface, and the value is Bearer API key

Header nameHeader valueRequiredDescription
AuthorizationBearer API keyYesReplace API key with your real API key

Request parameters

NameTypeRequiredDescription
inputstringYesNatural language input
tableSizeintegerNoReturn the number of matching tables, the default is 10
dataSourceCollectionIdlongNoAI dataset ID, obtained from the second step

Body request parameter example

{
"input": "Sales in the past 3 days",
"tableSize": "10",
"dataSourceCollectionId": 12
}

Return example

The return result is a list of database table structures matched by natural language. The following is a sample json of the return result. Each object in data is a table structure related data.

Success:

{
"success": true,
"errorCode": "",
"errorMessage": "",
"data": [
{
"dataSourceId": 0,
"databaseName": "",
"schemaName": "",
"tableName": "",
"tableSchema": ""
}
],
"traceId": "",
"errorDetail": "",
"solutionLink": ""
}

Return the properties of the object in the result data

NameTypeDescription
dataSourceIdintegerData source connection ID
databaseNamestring / nullDatabase name
schemaNamestring / nullSchema name
tableNamestringTable name
tableSchemastringTable schema

Step 5: Get the token for AI call (required)

Pass in the database table structure and AI type to get the token for AI call. The database table structure in this step can be obtained from Step 4 or the database table structure managed by the user

Get the token for AI call

Interface address: https://api.chat2db-ai.com/api/ai/rest/prompt_a (opens in a new tab)

Interface method: POST

Authentication method

Get the API key obtained in Step 3, add Authorization to the Header in the request interface, and the value is Bearer API key

Header nameHeader valueRequiredDescription
AuthorizationBearer API keyYesReplace API key with your real API key

Request parameters

NameTypeRequiredDescription
questionTypestringYesAI question type, you can pass in the following enumeration value, the default value is NL_2_SQL. When calling with the first mode, you can use all the following AI functions, and when calling with the second mode, you cannot use DASHBOARD_GENERATION.
//Convert natural language to SQL
NL_2_SQL
//Explain SQL
SQL_EXPLAIN
//SQL optimization
SQL_OPTIMIZER
//Report generation
DASHBOARD_GENERATION
inputstringyesNatural language input
databaseTypestringnoDatabase type, must be passed when using natural language to SQL and report generation, otherwise only MySQL dialect can be generated
tableSchemasRestPromptTableRequest / nullnoRestPromptTableRequest list of table structure objects required for AI questions. For RestPromptTableRequest object properties, refer to the table below
languagestring / nullnoThe value is EN/ZH. When the value is ZH, Chinese is returned. When the value is EN, English is returned. The default value is ZH

RestPromptTableRequest properties

NameTypeRequiredConstraintsDescription
dataSourceIdinteger / nullNoNoneData source connection ID
databaseNamestring / nullNoNoneDatabase name
schemaNamestring / nullNoNoneSchema name
tableNamestring / nullNoNoneTable name
tableSchemastring / nullNoNoneTable schema

Body request parameter example

{
"questionType": "NL_2_SQL",
"input": "Sales in the past three months",
"databaseType": "MYSQL",
"tableSchemas": [
{
"dataSourceId": 0,
"databaseName": "Database database name",
"schemaName": "Database schema name",
"tableName": "Table name",
"tableSchema": "Table ddl"
}
],
"language": "ZH"
}

Return example

Success:

{
"success": true,
"errorCode": "",
"errorMessage": "",
"errorDetail": "",
"solutionLink": "",
"data": {
"token": "API call token",
"apiParams": ""
},
"traceId": ""
}

Return result attributes

NameTypeDescription
successboolean / nullSuccess
errorCodestring / nullError code
errorMessagestring / nullError message
errorDetailstring / nullerror detail
solutionLinkstring / nullsolution link
dataRestPromptVOAI call Token information, please refer to the following table for RestPromptVO object attributes
traceIdstring / nulltraceId

RestPromptVO attributes

NameTypeDescription
tokenstring / nulltoken
apiParamsstring / nullAdditional information for request parameters

Step 6: AI call (required)

Use the token obtained in Step 5 to call the AI ​​interface. The AI ​​interface supports streaming and non-streaming calls

AI call interface

Interface address: https://api.chat2db-ai.com/api/ai/rest/chat_a (opens in a new tab)

Interface method: GET

Authentication method

Get the API key obtained in the second step, add Authorization to the Header in the request interface, and the value is Bearer API key

Header nameHeader valueRequiredDescription
AuthorizationBearer API keyYesReplace API key with your real API key

Request parameters

NameTypeRequiredDescription
tokenstringYesThe token obtained in the fifth step, because this interface is a GET method, it is best to URLEncode the token, otherwise the special characters in the token may be lost
streamstringyesWhether it is streaming, true is a streaming call, false is a non-streaming call
timeoutlongnoStreaming conversation timeout, in minutes, the default is 30 minutes

Request example

https://api.chat2db-ai.com/api/ai/rest/chat_a?token=sd***as&stream=true&timeout=30

Return example

This interface uses the SseEmitter protocol. The example of the result object returned by SseEmitter each time is as follows. When the output result is [DONE], it means the output is finished, otherwise one data object is output each time. The value of content is the content output by AI.

Streaming output example:

First output
{
"role": "assistant",
"content": "SELECT "
}
Second output
{
"role": "assistant",
"content": "*\n"
}
Third output
{
"role": "assistant",
"content": "FROM "
}
Fourth output
{
"role": "assistant",
"content": "table_name;\n"
}
Final output
[DONE]

Non-streaming output example:

Output all results
{
"role": "assistant",
"content": "SELECT *\nFROM table_name;\n"
}
Final output
[DONE]