# AI Assistant
### Create a New AI Assistant
POST `/api/chatbots/`
#### Request Body
**Parameters**
| Field | Type | Required | Description |
| ----------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Yes | The name of the bot. In Agent mode, it has semantic meaning. In other modes, it is only used to distinguish different bots. |
| rag | string (uuid) | No | RAG (Retrieval-Augmented Generation) settings, used to enhance the quality of responses. |
| largeLanguageModel | string (uuid) | Yes | The large language model used by the bot to generate responses. |
| embeddingModel | string (uuid) | No | The embedding model used for vectorizing text. This is an optional field. |
| rerankerModel | string (uuid) | No | |
| instructions | string | No | The bot's role instructions, used to describe the bot's role and behavior. |
| knowledgeBases | array\[IdName] | No | A list of knowledge bases accessible to the bot. |
| organization | string (uuid) | No | The organization the bot belongs to. If empty, it is a personal bot. |
| builtInWorkflow | string (uuid) | No | Built-in workflow, used for predefined processing flows. |
| replyMode | object | No | Reply mode: normal reply or streaming reply. `normal`: Normal; `template`: Template; `hybrid`: Hybrid; `workflow`: Workflow; `agent`: Agent. |
| template | string | No | The template used in Template mode and Hybrid mode. |
| unanswerableTemplate | string | No | The template used when an answer cannot be provided in Template mode and Hybrid mode. |
| totalWordsCount | integer (int64) | No | The cumulative total word count used. |
| outputMode | object | No | Output mode: text, table, or custom format. `text`: Text; `json_schema`: JSON Schema. |
| rawOutputFormat | object | No | The JSON structure definition for a custom output format. |
| databaseUrl | string | No | Database connection URL (used for database query functionality). |
| databaseType | string | No | Database type options, including MySQL, PostgreSQL, MSSQL, Oracle. |
| includeTables | object | No | A list of included tables (used for database query functionality). |
| groups | array\[IdName] | No | A list of groups accessible to the bot. |
| toolkits | array\[ToolSummary] | No | A list of toolkits used by the bot. |
| tools | array\[ToolSummary] | No | A list of tools that can be used by the bot. |
| agentMode | object | No | Agent mode: normal, SQL, or workflow mode. `normal`: Normal; `canvas`: Canvas. |
| numberOfRetrievedChunks | integer | No | The number of retrieved reference chunks. Default is 12, minimum is 1. |
| enableEvaluation | boolean | No | |
| enableInLineCitations | boolean | No | Enables the inline citation feature, which will insert citation markers in the format of \[1]\[2] in the response. |
**Request Structure Example**
```typescript
{
"name": string // The name of the bot. It has semantic meaning in Agent mode; in other modes, it's just used to distinguish different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text (optional)
"rerankerModel"?: string (uuid) // optional
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // List of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
}
]
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in template mode and hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when a response cannot be provided in template or hybrid mode (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // optional
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in [1][2] format into the response (optional)
}
```
**Request Example Value**
```json
{
"name": "Sample Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Sample String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Sample String",
"unanswerableTemplate": "Sample String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Sample String",
"databaseType": "Sample String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Call API Example (Shell)
curl -X POST "https://api.maiagent.ai/api/chatbots/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}'
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example string",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example string",
"unanswerableTemplate": "Example string",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example string",
"databaseType": "Example string",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
};
axios.post("https://api.maiagent.ai/api/chatbots/", data, config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": None,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": None,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": True,
"enableInLineCitations": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/chatbots/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 201**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"name": string // The name of the bot. It has semantic meaning in Agent mode; in other modes, it's just used to distinguish different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses.
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text, an optional item (optional)
"rerankerModel"?: string (uuid) // (optional)
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // A list of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in template mode and hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when the bot cannot answer in template mode and hybrid mode (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // The number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // (optional)
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in the format [1][2] in the response (optional)
}
```
**Response Example Value**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Response String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"updatedAt": "Response String",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Response String",
"unanswerableTemplate": "Response String",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Response String",
"databaseType": "Response String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInLineCitations": false
}
```
***
### List Embedding Models
GET `/api/embedding-models/`
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/embedding-models/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/embedding-models/", config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/embedding-models/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/embedding-models/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
[
{
"id": string (uuid)
"name": string
"isDefault"?: boolean // Optional
"icon":
{
"id": string (uuid)
"name": string
"image": string (uri)
}
}
]
```
**Example Response Value**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"isDefault": false,
"icon": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"image": "https://example.com/file.jpg"
}
}
]
```
***
### List Reranker Models
GET `/api/reranker-models/`
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/reranker-models/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/reranker-models/", config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/reranker-models/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("An error occurred with the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/reranker-models/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred with the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Response Schema Example**
```typescript
[
{
"id": string (uuid)
"name": string
"isDefault"?: boolean // optional
"icon":
{
"id": string (uuid)
"name": string
"image": string (uri)
}
}
]
```
**Response Example Value**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"isDefault": false,
"icon": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"image": "https://example.com/file.jpg"
}
}
]
```
***
### Get AI Assistant List
GET `/api/chatbots/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------------- | -------- | ------- | ---------------------------------------------- |
| `largeLanguageModel` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `pagination` | ❌ | string | Whether to paginate (true/false) |
| `query` | ❌ | string | |
| `replyMode` | ❌ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Please replace YOUR_API_KEY and check the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully got response:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"name": string // The name of the bot. In Agent mode, it has semantic meaning; in other modes, it's just used to differentiate between different bots.
"groups": [
{
"id": string (uuid)
"name": string
}
]
"rag": { // Base serializer for RAG
{
"id": string (uuid)
"name": string
}
}
"largeLanguageModel": { // Base serializer for LLM, includes only basic fields
{
"id": string (uuid)
"name": string
}
}
"embeddingModel": {
{
"id": string (uuid)
"name": string
"isDefault"?: boolean // Optional
"icon":
{
"id": string (uuid)
"name": string
"image": string (uri)
}
}
}
"rerankerModel": {
{
"id": string (uuid)
"name": string
"isDefault"?: boolean // Optional
"icon":
{
"id": string (uuid)
"name": string
"image": string (uri)
}
}
}
"knowledgeBases": [
{
"id": string (uuid)
"name": string
}
]
"tools": [
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"toolkits": [
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"agentMode"?: // Agent mode, can be canvas mode or normal mode. Canvas mode uses a canvas to generate responses, while normal mode uses the standard method.
* `normal` - Normal
* `canvas` - Canvas (Optional)
{
}
"replyMode"?: // Reply mode, can be normal, template, hybrid, workflow, or agent mode.
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (Optional)
{
}
"updatedAt": string (timestamp)
"enableEvaluation"?: boolean // Optional
"enableInLineCitations"?: boolean // Enables the inline citation feature, which inserts citation markers in the format of [1][2] in the response (Optional)
"numberOfRetrievedChunks"?: integer // Optional
}
]
}
```
**Response Example Value**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"rag": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"largeLanguageModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"embeddingModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"isDefault": false,
"icon": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"image": "https://example.com/file.jpg"
}
},
"rerankerModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"isDefault": false,
"icon": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"image": "https://example.com/file.jpg"
}
},
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"agentMode": {},
"replyMode": {},
"updatedAt": "Response String",
"enableEvaluation": false,
"enableInLineCitations": false,
"numberOfRetrievedChunks": 456
}
]
}
```
***
### Get a specific AI assistant
GET `/api/chatbots/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Chatbot. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Please make sure to replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Successfully retrieved response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully got response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"name": string // The name of the bot. It has semantic meaning in Agent mode; in other modes, it's just used to differentiate between different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text, an optional item (optional)
"rerankerModel"?: string (uuid) // (optional)
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // A list of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in Template mode and Hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when Template mode or Hybrid mode cannot provide an answer (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // The number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // (optional)
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in the [1][2] format in the response (optional)
}
```
**Response Example Value**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Response String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"updatedAt": "Response String",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Response String",
"unanswerableTemplate": "Response String",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Response String",
"databaseType": "Response String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInLineCitations": false
}
```
***
### Update AI Assistant
PUT `/api/chatbots/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Chatbot. |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Yes | The name of the bot. In Agent mode, it has semantic meaning; in other modes, it is only used to distinguish different bots. |
| rag | string (uuid) | No | RAG (Retrieval-Augmented Generation) settings, used to enhance the quality of answers. |
| largeLanguageModel | string (uuid) | Yes | The large language model used by the bot to generate answers. |
| embeddingModel | string (uuid) | No | The embedding model used for vectorizing text; this is an optional field. |
| rerankerModel | string (uuid) | No | |
| instructions | string | No | The role instructions for the bot, used to describe its role and behavior. |
| knowledgeBases | array\[IdName] | No | A list of knowledge bases accessible to the bot. |
| organization | string (uuid) | No | The organization the bot belongs to. If empty, it is a personal bot. |
| builtInWorkflow | string (uuid) | No | Built-in workflow for predefined processing flows. |
| replyMode | object | No | Reply mode: normal reply or streaming reply. `normal`: Normal; `template`: Template; `hybrid`: Hybrid; `workflow`: Workflow; `agent`: Agent. |
| template | string | No | The template used in Template mode and Hybrid mode. |
| unanswerableTemplate | string | No | The template used when Template mode or Hybrid mode cannot provide an answer. |
| totalWordsCount | integer (int64) | No | The cumulative total word count used. |
| outputMode | object | No | Output mode: text, table, or custom format. `text`: Text; `json_schema`: JSON Schema. |
| rawOutputFormat | object | No | The JSON structure definition for a custom output format. |
| databaseUrl | string | No | Database connection URL (for database query functionality). |
| databaseType | string | No | Database type options, including MySQL, PostgreSQL, MSSQL, Oracle. |
| includeTables | object | No | A list of included tables (for database query functionality). |
| groups | array\[IdName] | No | A list of groups accessible to the bot. |
| toolkits | array\[ToolSummary] | No | A list of toolkits used by the bot. |
| tools | array\[ToolSummary] | No | A list of tools that can be used by the bot. |
| agentMode | object | No | Agent mode: normal, SQL, or workflow mode. `normal`: Normal; `canvas`: Canvas. |
| numberOfRetrievedChunks | integer | No | The number of retrieved reference chunks. The default is 12, and the minimum is 1. |
| enableEvaluation | boolean | No | |
| enableInLineCitations | boolean | No | Enables the inline citation feature, which will insert citation markers in the format of \[1]\[2] in the response. |
**Request Structure Example**
```typescript
{
"name": string // The name of the bot. It has semantic meaning in Agent mode; in other modes, it's just used to distinguish different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text (optional)
"rerankerModel"?: string (uuid) // (optional)
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // A list of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
}
]
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in Template mode and Hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when Template mode or Hybrid mode cannot provide an answer (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // (optional)
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in [1][2] format in the response (optional)
}
```
**Request Example Value**
```json
{
"name": "Sample Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Sample String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Sample String",
"unanswerableTemplate": "Sample String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Sample String",
"databaseType": "Sample String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}'
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
};
axios.put("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
response = requests.put(url, json=data, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"name": string // The name of the bot. In Agent mode, it has semantic meaning. In other modes, it's just used to distinguish different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text, an optional item (optional)
"rerankerModel"?: string (uuid) // optional
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // A list of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in template mode and hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when template mode or hybrid mode cannot provide an answer (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // The number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // optional
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in the format of [1][2] in the response (optional)
}
```
**Example Response Value**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Response String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"updatedAt": "Response String",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Response String",
"unanswerableTemplate": "Response String",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Response String",
"databaseType": "Response String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInLineCitations": false
}
```
***
### Partially Update AI Assistant
PATCH `/api/chatbots/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Chatbot. |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | No | The name of the bot. In Agent mode, it has semantic meaning. In other modes, it is just used to distinguish different bots. |
| rag | string (uuid) | No | RAG (Retrieval-Augmented Generation) settings, used to enhance response quality. |
| largeLanguageModel | string (uuid) | No | The Large Language Model used by the bot to generate responses. |
| embeddingModel | string (uuid) | No | The embedding model used to vectorize text, an optional field. |
| rerankerModel | string (uuid) | No | |
| instructions | string | No | The bot's role instructions, used to describe the bot's role and behavior. |
| knowledgeBases | array\[IdName] | No | A list of knowledge bases accessible to the bot. |
| organization | string (uuid) | No | The organization the bot belongs to. If empty, it is a personal bot. |
| builtInWorkflow | string (uuid) | No | Built-in workflow, used for predefined processing flows. |
| replyMode | object | No | Reply mode: normal reply or streaming reply. `normal`: Normal; `template`: Template; `hybrid`: Hybrid; `workflow`: Workflow; `agent`: Agent; |
| template | string | No | The template used in Template mode and Hybrid mode. |
| unanswerableTemplate | string | No | The template used when unable to answer in Template mode and Hybrid mode. |
| totalWordsCount | integer (int64) | No | Cumulative total word count used. |
| outputMode | object | No | Output mode: text, table, or custom format. `text`: Text; `json_schema`: JSON Schema; |
| rawOutputFormat | object | No | JSON structure definition for custom output format. |
| databaseUrl | string | No | Database connection URL (for database query function). |
| databaseType | string | No | Database type options, including MySQL, PostgreSQL, MSSQL, Oracle. |
| includeTables | object | No | List of included tables (for database query function). |
| groups | array\[IdName] | No | A list of groups accessible to the bot. |
| toolkits | array\[ToolSummary] | No | A list of toolkits used by the bot. |
| tools | array\[ToolSummary] | No | A list of tools that can be used by the bot. |
| agentMode | object | No | Agent mode: Normal, SQL, or Workflow mode. `normal`: Normal; `canvas`: Canvas; |
| numberOfRetrievedChunks | integer | No | The number of retrieved reference chunks, default is 12, minimum is 1. |
| enableEvaluation | boolean | No | |
| enableInLineCitations | boolean | No | Enables the inline citation feature, which will insert citation markers in the format \[1]\[2] in the response. |
**Request Structure Example**
```typescript
{
"name"?: string // The name of the bot. In Agent mode, it has semantic meaning; in other modes, it's just used to distinguish different bots (optional)
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel"?: string (uuid) // The large language model used by the bot for generating responses (optional)
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text, an optional item (optional)
"rerankerModel"?: string (uuid) // optional
"instructions"?: string // The bot's role instructions, used to describe its role and behavior (optional)
"knowledgeBases"?: [ // A list of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
}
]
"organization"?: string (uuid) // The organization the bot belongs to; if empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in template and hybrid modes (optional)
"unanswerableTemplate"?: string // The template used when a response cannot be generated in template and hybrid modes (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // optional
"enableInLineCitations"?: boolean // Enable inline citation feature, which will insert markers like [1][2] in the response (optional)
}
```
**Request Example Value**
```json
{
"name": "Sample Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Sample String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Sample String",
"unanswerableTemplate": "Sample String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Sample String",
"databaseType": "Sample String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Call API Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}'
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
};
axios.patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": None,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": None,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": True,
"enableInLineCitations": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "Example Name",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Example String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Example String",
"unanswerableTemplate": "Example String",
"totalWordsCount": 123,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Example String",
"databaseType": "Example String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 123,
"enableEvaluation": true,
"enableInLineCitations": true
}
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"name": string // The name of the bot. In Agent mode, it has semantic meaning. In other modes, it's just used to distinguish different bots.
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) settings, used to enhance response quality (optional)
"largeLanguageModel": string (uuid) // The large language model used by the bot to generate responses.
"embeddingModel"?: string (uuid) // The embedding model used for vectorizing text, an optional item (optional)
"rerankerModel"?: string (uuid) // optional
"instructions"?: string // The bot's role instructions, used to describe the bot's role and behavior (optional)
"knowledgeBases"?: [ // List of knowledge bases accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // The organization the bot belongs to. If empty, it's a personal bot (optional)
"builtInWorkflow"?: string (uuid) // Built-in workflow, used for predefined processing flows (optional)
"replyMode"?: // Reply mode: normal reply or streaming reply
* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `workflow` - Workflow
* `agent` - Agent (optional)
{
}
"template"?: string // The template used in template mode and hybrid mode (optional)
"unanswerableTemplate"?: string // The template used when template mode or hybrid mode cannot provide an answer (optional)
"totalWordsCount"?: integer (int64) // Cumulative total word count used (optional)
"outputMode"?: // Output mode: text, table, or custom format
* `text` - Text
* `json_schema` - JSON Schema (optional)
{
}
"rawOutputFormat"?: object // JSON structure definition for custom output format (optional)
"databaseUrl"?: string // Database connection URL (for database query functionality) (optional)
"databaseType"?: string // Database type options, including MySQL, PostgreSQL, MSSQL, Oracle (optional)
"includeTables"?: object // List of included tables (for database query functionality) (optional)
"groups"?: [ // List of groups accessible to the bot (optional)
{
"id": string (uuid)
"name": string
}
]
"toolkits"?: [ // List of toolkits used by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"tools"?: [ // List of tools usable by the bot (optional)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"agentMode"?: // Agent mode: normal, SQL, or workflow mode
* `normal` - Normal
* `canvas` - Canvas (optional)
{
}
"numberOfRetrievedChunks"?: integer // The number of retrieved reference chunks, default is 12, minimum is 1 (optional)
"enableEvaluation"?: boolean // optional
"enableInLineCitations"?: boolean // Enable inline citations, which will insert citation markers in [1][2] format in the response (optional)
}
```
**Response Example Value**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "Response String",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"updatedAt": "Response String",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "Response String",
"unanswerableTemplate": "Response String",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"databaseUrl": "Response String",
"databaseType": "Response String",
"includeTables": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"toolkits": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"displayName": "Response String",
"toolType": "Response String"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInLineCitations": false
}
```
***
### Delete AI Assistant
DELETE `/api/chatbots/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Chatbot. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Please replace YOUR_API_KEY and verify the request data before execution.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request payload
const data = null;
axios.delete("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully received response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Successfully received response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully received response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
| Status Code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.maiagent.ai/api/api-doc-en/api-reference/ai-zhu-li.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.