> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/api-reference/zhi-shi-ku-xin-ban.md).
# Knowledge Bases (New)
### Create a Knowledge Base
POST `/api/v1/knowledge-bases/`
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| embeddingModel | string (uuid) | Yes | |
| rerankerModel | string (uuid) | Yes | |
| name | string | Yes | |
| description | string | No | |
| numberOfRetrievedChunks | integer | No | Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 |
| enableHyde | boolean | No | Enable HyDE; defaults to False |
| similarityCutoff | number (double) | No | Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 |
| enableRerank | boolean | No | Whether to enable reranking; defaults to True |
| enableRrf | boolean | No | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default. |
| vectorDatabaseType | object | No | Type of vector database: elasticsearch, opensearch, oracle or synxdb. Defaults to the platform-managed engine. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database ... |
| vectorDatabaseUrl | string | No | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., ""). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey | string | No | API Key for Elasticsearch. Not used for OpenSearch. |
| opensearchUsername | string | No | Username for OpenSearch Basic Auth. |
| opensearchPassword | string | No | Password for OpenSearch Basic Auth. |
| oracleUser | string | No | Oracle database username. |
| oraclePassword | string | No | Oracle database password. |
| synxdbUser | string | No | SynxDB database username. |
| synxdbPassword | string | No | SynxDB database password. |
| chatbots | array\[IdName] | No | |
| groups | array\[IdName] | No | |
**Request Schema Example**
```typescript
{
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch, opensearch, oracle or synxdb. Defaults to the platform-managed engine.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"chatbots"?: [ // Optional
{
"id": string (uuid)
}
]
"groups"?: [ // Optional
{
"id": string (uuid)
}
]
}
```
**Example Request Values**
```json
{
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API Call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/", data, config)
.then(response => {
console.log('Response Received Successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request Error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": True,
"similarityCutoff": 123,
"enableRerank": True,
"enableRrf": True,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response Received Successfully:")
print(response.json())
except Exception as e:
print("Request Error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
'name' => 'Example Name',
'description' => 'Example String',
'numberOfRetrievedChunks' => 123,
'enableHyde' => true,
'similarityCutoff' => 123,
'enableRerank' => true,
'enableRrf' => true,
'vectorDatabaseType' => new \stdClass(),
'vectorDatabaseUrl' => 'Example String',
'vectorDatabaseApiKey' => 'Example String',
'opensearchUsername' => 'Example String',
'opensearchPassword' => 'Example String',
'oracleUser' => 'Example String',
'oraclePassword' => 'Example String',
'synxdbUser' => 'Example String',
'synxdbPassword' => 'Example String',
'chatbots' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response Received Successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request Error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 201**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that the knowledge base can access (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response String",
"vectorDatabaseApiKey": "Response String",
"opensearchUsername": "Response String",
"opensearchPassword": "Response String",
"oracleUser": "Response String",
"oraclePassword": "Response String",
"synxdbUser": "Response String",
"synxdbPassword": "Response String",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response String",
"updatedAt": "Response String"
}
```
***
### List All Knowledge Bases
GET `/api/v1/knowledge-bases/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `embeddingModel` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
| `rerankerModel` | ❌ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API Call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", config)
.then(response => {
console.log('Response Received Successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request Error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response Received Successfully:")
print(response.json())
except Exception as e:
print("Request Error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", [
'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 Error: ' . $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)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that the knowledge base can access (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```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",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response String",
"vectorDatabaseApiKey": "Response String",
"opensearchUsername": "Response String",
"opensearchPassword": "Response String",
"oracleUser": "Response String",
"oraclePassword": "Response String",
"synxdbUser": "Response String",
"synxdbPassword": "Response String",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response String",
"updatedAt": "Response String"
}
]
}
```
***
### Retrieve Details of a Specific Knowledge Base
GET `/api/v1/knowledge-bases/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API Call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, minimum 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, range 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response string",
"vectorDatabaseApiKey": "Response string",
"opensearchUsername": "Response string",
"opensearchPassword": "Response string",
"oracleUser": "Response string",
"oraclePassword": "Response string",
"synxdbUser": "Response string",
"synxdbPassword": "Response string",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Search the Contents of a Specific Knowledge Base
POST `/api/v1/knowledge-bases/{id}/search/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
| `embeddingModel` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
| `rerankerModel` | ❌ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| searchMode | object | No | Search mode: hybrid (default, vector + BM25), semantic (vector only), keyword (BM25 only) `hybrid`: Hybrid (vector + BM25) ; `semantic`: Semantic (vector only) ; `keyword`: Keyword (BM25 only); |
| queryMetadata | object | No | Query metadata used to control the search scope and method |
**Example Request Schema**
```typescript
{
"searchMode"?: // Search mode: hybrid (default, vector + BM25), semantic (vector only), keyword (BM25 only)
* `hybrid` - Hybrid (vector + BM25)
* `semantic` - Semantic (vector only)
* `keyword` - Keyword (BM25 only) (Optional)
{
}
"queryMetadata"?: object // Query metadata used to control the search scope and method (Optional)
}
```
**Example Request Values**
```json
{
"query": "How to use the API"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/search/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How to use the API"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"query": "How to use the API"
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/search/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/search/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"query": "How to use the API"
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/search/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'query' => 'How to use the API'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"charactersCount": integer
"hitsCount": integer
"text": string
"updatedAt": string (timestamp)
"filename": string
"chatbotFile": object // Return the complete ChatbotFile information, including the file URL and type, to support frontend image previews
"knowledgeBaseFile": object // Same as get_chatbot_file, for backward compatibility
"pageNumber": integer // Backward-compatible alias of ``page_start``.
"pageStart": integer
"pageEnd": integer
"citationTitle": string // Source title shown on the inline citation hover card.
"citationDescription": string // Source description shown on the inline citation hover card.
"citationQuote": string // Quoted text snippet shown on the inline citation hover card.
"hasImage": boolean // Determine whether an image is present (check the file type or Markdown images in text)
"imageUrl": string // Extract the image URL (prefer the file URL; otherwise extract it from Markdown)
"displayText": string // Return the full text with Markdown image markup removed
"displayTitle": string // Return the display title (fallback: citation_title -> filename)
"highlightedText": string // Return text with matched terms wrapped in ```` tags.
Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Metadata keys and values defined by the user. (Optional)
"metadataEnabledForSearch": object // Map each user-defined metadata key on this node to whether it was sent into the LLM.
A key reaches the LLM only when its ``MetadataKey.enabled_for_search`` is True *and*
the node carries a value for it. Since this maps over ``raw_user_define_metadata``
(the keys the cited-documents block displays, all of which have a value),
``enabled_for_search`` alone decides the flag. The source of truth is the node's
knowledge base ``MetadataKey`` current setting, matching the AI Search indicator.
"startCharIdx": integer
"endCharIdx": integer
}
]
}
```
**Example Response Values**
```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",
"charactersCount": 456,
"hitsCount": 456,
"text": "Response string",
"updatedAt": "Response string",
"filename": "Response string",
"chatbotFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"knowledgeBaseFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"pageNumber": 456,
"pageStart": 456,
"pageEnd": 456,
"citationTitle": "Response string",
"citationDescription": "Response string",
"citationQuote": "Response string",
"hasImage": false,
"imageUrl": "Response string",
"displayText": "Response string",
"displayTitle": "Response string",
"highlightedText": "Response string",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"metadataEnabledForSearch": {
"key1": "value1",
"key2": "value2",
"createdAt": "2025-01-01T00:00:00.000Z"
},
"startCharIdx": 456,
"endCharIdx": 456
}
]
}
```
***
### Update a Knowledge Base
PUT `/api/v1/knowledge-bases/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| organization | string (uuid) | No | |
| embeddingModel | string (uuid) | Yes | |
| rerankerModel | string (uuid) | Yes | |
| name | string | Yes | |
| description | string | No | |
| numberOfRetrievedChunks | integer | No | Number of reference chunks to retrieve; defaults to 12, minimum 1 |
| enableHyde | boolean | No | Enable HyDE; defaults to False |
| similarityCutoff | number (double) | No | Similarity threshold; defaults to 0.0, range 0.0-1.0 |
| enableRerank | boolean | No | Whether to enable reranking; defaults to True |
| enableRrf | boolean | No | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. |
| vectorDatabaseType | object | No | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai ; `synxdb`: SynxDB; |
| vectorDatabaseUrl | string | No | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., ""). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey | string | No | API Key for Elasticsearch. Not used for OpenSearch. |
| opensearchUsername | string | No | Username for OpenSearch Basic Auth. |
| opensearchPassword | string | No | Password for OpenSearch Basic Auth. |
| oracleUser | string | No | Oracle database username. |
| oraclePassword | string | No | Oracle database password. |
| synxdbUser | string | No | SynxDB database username. |
| synxdbPassword | string | No | SynxDB database password. |
| chatbots | array\[IdName] | No | |
| groups | array\[IdName] | No | List of groups that can access the knowledge base |
**Example Request Schema**
```typescript
{
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, minimum 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, range 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"chatbots"?: [ // Optional
{
"id": string (uuid)
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
}
]
}
```
**Example Request Values**
```json
{
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example name",
"description": "Example string",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example string",
"vectorDatabaseApiKey": "Example string",
"opensearchUsername": "Example string",
"opensearchPassword": "Example string",
"oracleUser": "Example string",
"oraclePassword": "Example string",
"synxdbUser": "Example string",
"synxdbPassword": "Example string",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example name",
"description": "Example string",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example string",
"vectorDatabaseApiKey": "Example string",
"opensearchUsername": "Example string",
"opensearchPassword": "Example string",
"oracleUser": "Example string",
"oraclePassword": "Example string",
"synxdbUser": "Example string",
"synxdbPassword": "Example string",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example name",
"description": "Example string",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example string",
"vectorDatabaseApiKey": "Example string",
"opensearchUsername": "Example string",
"opensearchPassword": "Example string",
"oracleUser": "Example string",
"oraclePassword": "Example string",
"synxdbUser": "Example string",
"synxdbPassword": "Example string",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": True,
"similarityCutoff": 123,
"enableRerank": True,
"enableRrf": True,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'organization' => '550e8400-e29b-41d4-a716-446655440000',
'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
'name' => 'Example Name',
'description' => 'Example String',
'numberOfRetrievedChunks' => 123,
'enableHyde' => true,
'similarityCutoff' => 123,
'enableRerank' => true,
'enableRrf' => true,
'vectorDatabaseType' => new \stdClass(),
'vectorDatabaseUrl' => 'Example String',
'vectorDatabaseApiKey' => 'Example String',
'opensearchUsername' => 'Example String',
'opensearchPassword' => 'Example String',
'oracleUser' => 'Example String',
'oraclePassword' => 'Example String',
'synxdbUser' => 'Example String',
'synxdbPassword' => 'Example String',
'chatbots' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response String",
"vectorDatabaseApiKey": "Response String",
"opensearchUsername": "Response String",
"opensearchPassword": "Response String",
"oracleUser": "Response String",
"oraclePassword": "Response String",
"synxdbUser": "Response String",
"synxdbPassword": "Response String",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response String",
"updatedAt": "Response String"
}
```
***
### Partially Update a Knowledge Base
PATCH `/api/v1/knowledge-bases/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| organization | string (uuid) | No | |
| embeddingModel | string (uuid) | No | |
| rerankerModel | string (uuid) | No | |
| name | string | No | |
| description | string | No | |
| numberOfRetrievedChunks | integer | No | Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 |
| enableHyde | boolean | No | Enable HyDE; defaults to False |
| similarityCutoff | number (double) | No | Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 |
| enableRerank | boolean | No | Whether to enable reranking; defaults to True |
| enableRrf | boolean | No | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. |
| vectorDatabaseType | object | No | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai ; `synxdb`: SynxDB; |
| vectorDatabaseUrl | string | No | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., ""). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey | string | No | API Key for Elasticsearch. Not used for OpenSearch. |
| opensearchUsername | string | No | Username for OpenSearch Basic Auth. |
| opensearchPassword | string | No | Password for OpenSearch Basic Auth. |
| oracleUser | string | No | Oracle database username. |
| oraclePassword | string | No | Oracle database password. |
| synxdbUser | string | No | SynxDB database username. |
| synxdbPassword | string | No | SynxDB database password. |
| chatbots | array\[IdName] | No | |
| groups | array\[IdName] | No | List of groups that can access the knowledge base |
**Example Request Schema**
```typescript
{
"organization"?: string (uuid) // Optional
"embeddingModel"?: string (uuid) // Optional
"rerankerModel"?: string (uuid) // Optional
"name"?: string // Optional
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"chatbots"?: [ // Optional
{
"id": string (uuid)
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
}
]
}
```
**Example Request Values**
```json
{
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# Before running, replace YOUR_API_KEY and verify the request data.
```
{% 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 body (payload)
const data = {
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": true,
"similarityCutoff": 123,
"enableRerank": true,
"enableRrf": true,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example Name",
"description": "Example String",
"numberOfRetrievedChunks": 123,
"enableHyde": True,
"similarityCutoff": 123,
"enableRerank": True,
"enableRrf": True,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Example String",
"vectorDatabaseApiKey": "Example String",
"opensearchUsername": "Example String",
"opensearchPassword": "Example String",
"oracleUser": "Example String",
"oraclePassword": "Example String",
"synxdbUser": "Example String",
"synxdbPassword": "Example String",
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'organization' => '550e8400-e29b-41d4-a716-446655440000',
'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000',
'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000',
'name' => 'Example Name',
'description' => 'Example String',
'numberOfRetrievedChunks' => 123,
'enableHyde' => true,
'similarityCutoff' => 123,
'enableRerank' => true,
'enableRrf' => true,
'vectorDatabaseType' => new \stdClass(),
'vectorDatabaseUrl' => 'Example String',
'vectorDatabaseApiKey' => 'Example String',
'opensearchUsername' => 'Example String',
'opensearchPassword' => 'Example String',
'oracleUser' => 'Example String',
'oraclePassword' => 'Example String',
'synxdbUser' => 'Example String',
'synxdbPassword' => 'Example String',
'chatbots' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String",
"description": "Response String",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response String",
"vectorDatabaseApiKey": "Response String",
"opensearchUsername": "Response String",
"opensearchPassword": "Response String",
"oracleUser": "Response String",
"oraclePassword": "Response String",
"synxdbUser": "Response String",
"synxdbPassword": "Response String",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response String"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response String",
"updatedAt": "Response String"
}
```
***
### Delete a Knowledge Base
DELETE `/api/v1/knowledge-bases/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
| Status Code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Check RRF Availability
GET `/api/v1/knowledge-bases/{id}/check-rrf-availability/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; default: 12, minimum: 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; default: False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; default: 0.0, range: 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; default: True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "Response string",
"vectorDatabaseApiKey": "Response string",
"opensearchUsername": "Response string",
"opensearchPassword": "Response string",
"oracleUser": "Response string",
"oraclePassword": "Response string",
"synxdbUser": "Response string",
"synxdbPassword": "Response string",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Export Labels to Excel
GET `/api/v1/knowledge-bases/{id}/export-labels-excel/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
| Status Code | Description |
| ----------- | ------------------- |
| 200 | Excel file download |
***
### Import Labels from Excel
POST `/api/v1/knowledge-bases/{id}/import-labels-excel/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "excelFile=@example_file.txt"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// Create a FormData object
const formData = new FormData();
// Replace with an actual file
formData.append('excelFile', /* Actual file object */, 'example_file.txt');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", formData, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# Prepare files and form data
files = {
'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}
response = requests.post(url, files=files, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'excelFile',
'contents' => fopen('example_file.txt', 'r'),
'filename' => 'example_file.txt'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"success"?: boolean // Optional
"updated_count"?: integer // Optional
"total_rows"?: integer // Optional
"errors"?: [ // Optional
{
"row"?: integer // Optional
"file_id"?: string // Optional
"error"?: string // Optional
}
]
}
```
**Example Response Values**
```json
{
"success": false,
"updated_count": 456,
"total_rows": 456,
"errors": [
{
"row": 456,
"file_id": "Response string",
"error": "Response string"
}
]
}
```
***
### Export Metadata to Excel
GET `/api/v1/knowledge-bases/{id}/export-metadata-excel/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
| Status Code | Description |
| ----------- | ------------------- |
| 200 | Excel file download |
***
### Import Metadata from Excel
POST `/api/v1/knowledge-bases/{id}/import-metadata-excel/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "excelFile=@example_file.txt"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// Create a FormData object
const formData = new FormData();
// Replace with an actual file
formData.append('excelFile', /* Actual file object */, 'example_file.txt');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", formData, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# Prepare files and form data
files = {
'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}
response = requests.post(url, files=files, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'excelFile',
'contents' => fopen('example_file.txt', 'r'),
'filename' => 'example_file.txt'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"success"?: boolean // Optional
"updated_count"?: integer // Optional
"total_rows"?: integer // Optional
"errors"?: [ // Optional
{
"row"?: integer // Optional
"file_id"?: string // Optional
"error"?: string // Optional
}
]
}
```
**Example Response Values**
```json
{
"success": false,
"updated_count": 456,
"total_rows": 456,
"errors": [
{
"row": 456,
"file_id": "Response string",
"error": "Response string"
}
]
}
```
***
### Create a New Label
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------- |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----- | ------ | -------- | ----------- |
| name | string | Yes | |
**Request Schema Example**
```typescript
{
"name": string
}
```
**Example Request Values**
```json
{
"name": "Example name"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"name": "Example name"
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"name": "Example name"
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 201**
**Example response schema**
```typescript
{
"id": string (uuid)
"name"?: string // Optional
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
```
***
### List labels in the knowledge base
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------- | ---------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"name"?: string // Optional
}
]
}
```
**Example response values**
```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"
}
]
}
```
***
### Get details of a specific label
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ---------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this knowledge base label. |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"name"?: string // Optional
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
```
***
### Update a label
PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ---------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this knowledge base label. |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| ----- | ------ | -------- | ----------- |
| name | string | Yes | |
**Example request schema**
```typescript
{
"name": string
}
```
**Example request values**
```json
{
"name": "Example name"
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"name": "Example name"
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"name": "Example name"
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"name"?: string // Optional
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
```
***
### Partially update a label
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ---------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this knowledge base label. |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| ----- | ------ | -------- | ----------- |
| name | string | No | |
**Example request schema**
```typescript
{
"name"?: string // Optional
}
```
**Example request values**
```json
{
"name": "Example name"
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"name": "Example name"
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"name": "Example name"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"name"?: string // Optional
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
```
***
### Delete a label
DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ---------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this knowledge base label. |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Create a metadata field
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------- |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| ---------------- | ------- | -------- | ------------------------------------------ |
| keyName | string | Yes | Metadata key name |
| description | string | No | Description of the purpose of this field |
| isRequired | boolean | No | Whether this field is required |
| defaultValue | string | No | Default value for new files |
| enabledForSearch | boolean | No | Whether to use this field during retrieval |
**Example request schema**
```typescript
{
"keyName": string // Metadata key name
"description"?: string // Description of the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
}
```
**Example request values**
```json
{
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"keyName": "Example string",
"description": "Example string",
"isRequired": True,
"defaultValue": "Example string",
"enabledForSearch": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'keyName' => 'Example string',
'description' => 'Example string',
'isRequired' => true,
'defaultValue' => 'Example string',
'enabledForSearch' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 201**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
"keyName": string // Metadata key name
"keyType": string // Automatically determined from the field name (default or custom field)
"description"?: string // Describes the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"keyName": "Response string",
"keyType": "Response string",
"description": "Response string",
"isRequired": false,
"defaultValue": "Response string",
"enabledForSearch": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### List Metadata Fields
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------- | ---------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `pagination` | ❌ | boolean | Set to false to return all keys without pagination (defaults to true). |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?page=1&pageSize=1&pagination=true" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?page=1&pageSize=1&pagination=true", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?page=1&pageSize=1&pagination=true"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?page=1&pageSize=1&pagination=true", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
"keyName": string // Metadata key name
"keyType": string // Automatically determined from the field name (default or custom field)
"description"?: string // Describes the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```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",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"keyName": "Response string",
"keyType": "Response string",
"description": "Response string",
"isRequired": false,
"defaultValue": "Response string",
"enabledForSearch": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Retrieve a Specific Metadata Field
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Metadata Key. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
"keyName": string // Metadata key name
"keyType": string // Automatically determined from the field name (default or custom field)
"description"?: string // Describes the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"keyName": "Response string",
"keyType": "Response string",
"description": "Response string",
"isRequired": false,
"defaultValue": "Response string",
"enabledForSearch": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Update a Metadata Field
PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Metadata Key. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ---------------- | ------- | -------- | ------------------------------------------ |
| keyName | string | Yes | Metadata key name |
| description | string | No | Describes the purpose of this field |
| isRequired | boolean | No | Whether this field is required |
| defaultValue | string | No | Default value for new files |
| enabledForSearch | boolean | No | Whether to use this field during retrieval |
**Example Request Schema**
```typescript
{
"keyName": string // Metadata key name
"description"?: string // Describes the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
}
```
**Example Request Values**
```json
{
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"keyName": "Example string",
"description": "Example string",
"isRequired": true,
"defaultValue": "Example string",
"enabledForSearch": true
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"keyName": "Example string",
"description": "Example string",
"isRequired": True,
"defaultValue": "Example string",
"enabledForSearch": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'keyName' => 'Example string',
'description' => 'Example string',
'isRequired' => true,
'defaultValue' => 'Example string',
'enabledForSearch' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
"keyName": string // Metadata key name
"keyType": string // Automatically determined from the field name (default or custom field)
"description"?: string // Describes the purpose of this field (Optional)
"isRequired"?: boolean // Whether this field is required (Optional)
"defaultValue"?: string // Default value for new files (Optional)
"enabledForSearch"?: boolean // Whether to use this field during retrieval (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"keyName": "Response string",
"keyType": "Response string",
"description": "Response string",
"isRequired": false,
"defaultValue": "Response string",
"enabledForSearch": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Upload Files to a Knowledge Base
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `fileType` | ❌ | string | Filter by file type, such as pdf, docx, txt, xlsx, etc. |
| `knowledgeBase` | ❌ | string | Knowledge base ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | Search keywords; supports multiple space-separated criteria. Searchable fields: file ID, filename, label name, Metadata value |
| `status` | ❌ | string | Filter by file status. Available values: initial (initial), processing (processing), done (done), deleting (deleting), deleted (deleted), failed (failed) \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----- | ------------------------------- | -------- | ----------------------------------------------- |
| files | array\[KnowledgeBaseFileCreate] | Yes | Supports uploading multiple files in one batch. |
**Example Request Schema**
```typescript
{
"files": [ // Supports uploading multiple files in one batch.
{
"filename": string // Filename
"file": string (uri) // File to upload
"parser"?: string (uuid) // Optional
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
"asrOptions"?: object // Per-file canonical transcription options (languages, prompt, diarization). Empty means no per-file options: provider defaults apply. Completely decoupled from user-defined metadata; never indexed for search. (Optional)
}
]
}
```
**Example Request Values**
```json
{
"files": [
{
"filename": "my-file.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"labels": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "my-label"
}
],
"rawUserDefineMetadata": {
"key1": "value1",
"key2": "value2"
}
},
{
"filename": "you-can-upload-multiple-files.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"files": [
{
"filename": "my-file.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"labels": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "my-label"
}
],
"rawUserDefineMetadata": {
"key1": "value1",
"key2": "value2"
}
},
{
"filename": "you-can-upload-multiple-files.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"files": [
{
"filename": "my-file.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"labels": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "my-label"
}
],
"rawUserDefineMetadata": {
"key1": "value1",
"key2": "value2"
}
},
{
"filename": "you-can-upload-multiple-files.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"files": [
{
"filename": "my-file.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"labels": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "my-label"
}
],
"rawUserDefineMetadata": {
"key1": "value1",
"key2": "value2"
}
},
{
"filename": "you-can-upload-multiple-files.pdf",
"file": "string",
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'files' => [
[
'filename' => 'my-file.pdf',
'file' => 'string',
'parser' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'labels' => [
[
'id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'name' => 'my-label'
]
],
'rawUserDefineMetadata' => [
'key1' => 'value1',
'key2' => 'value2'
]
],
[
'filename' => 'you-can-upload-multiple-files.pdf',
'file' => 'string',
'parser' => '3fa85f64-5717-4562-b3fc-2c963f66afa6'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 201**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"filename": string // Filename
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, disabled; null when completed
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a user-selected parser, files uploaded before launch, or files queued for reassessment
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, vision_unavailable; more categories may be added later. Display a generic message when no matching text is available
"facts": object // Numeric facts supporting the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (number of characters in the body); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable derived pdf file (displayed using the PDF viewer in the frontend); None for other files.
Generate URLs with the same CustomizedFileFieldSerializer as the `file` field to ensure consistent formatting (including each
storage provider's presign/host rules). Do not use get_absolute_url() because it produces incorrectly formatted URLs.
"createdAt": string (timestamp)
}
]
}
```
**Example Response Values**
```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",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
]
}
```
***
### Update File Metadata
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/update-metadata/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | ----------- |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
**Example Request Schema**
```typescript
{
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
}
```
**Example Request Values**
```json
{
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/update-metadata/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/update-metadata/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/update-metadata/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/update-metadata/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"filename": string // Filename
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, disabled; null when completed
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a user-selected parser, files uploaded before launch, or files queued for reassessment
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, vision_unavailable; more categories may be added later. Display a generic message when no matching text is available
"facts": object // Numeric facts supporting the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (number of characters in the body); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable derived pdf file (displayed using the PDF viewer in the frontend); None for other files.
Generate URLs with the same CustomizedFileFieldSerializer as the `file` field to ensure consistent formatting (including each
storage provider's presign/host rules). Do not use get_absolute_url() because it produces incorrectly formatted URLs.
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
```
***
### Batch Delete Files
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/batch-delete/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------- |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ----- | -------------- | -------- | ----------- |
| ids | array\[string] | Yes | |
**Request Schema Example**
```typescript
{
"ids": [
string (uuid)
]
}
```
**Example Request Values**
```json
{
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'ids' => [
'550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"queued": [
string (uuid)
]
"skipped": [
{
"id": string (uuid)
"reason": string (enum: deleting) // * `deleting` - deleting
}
]
}
```
**Example Response Values**
```json
{
"queued": [
"550e8400-e29b-41d4-a716-446655440000"
],
"skipped": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"reason": "deleting"
}
]
}
```
***
### Reparse Files in Bulk
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/files/batch-reparse/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `fileType` | ❌ | string | Filter by file type, such as pdf, docx, txt, xlsx, etc. |
| `knowledgeBase` | ❌ | string | Knowledge base ID |
| `query` | ❌ | string | Search keywords. Supports multiple search terms separated by spaces. Searchable fields: file ID, filename, label name, and metadata value |
| `status` | ❌ | string | Filter by file status. Available values: initial (initialized), processing (processing), done (completed), deleting (being deleted), deleted (deleted), failed (failed) \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |
#### Code Examples
{% tabs %} {% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&query=example&status=delete_failed" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[]'
# Replace YOUR_API_KEY and verify the request data before running.
```
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = [];
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&query=example&status=delete_failed", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&query=example&status=delete_failed"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = []
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&query=example&status=delete_failed", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => []
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
[
{
"id": string (uuid)
"filename": string // Filename
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, or off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, or disabled; null when completed
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a manually selected parser, files uploaded before this feature launched, or files queued for reevaluation
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, or vision_unavailable; new categories may be added later. Display a generic message if no matching text is available
"facts": object // Numeric facts behind the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (number of characters in the body); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a derived PDF file for preview (displayed using the frontend PDF viewer); None for other file types.
Generate the URL using the same CustomizedFileFieldSerializer as the `file` field to ensure a consistent format (including each
storage provider's presign/host rules). Do not use get_absolute_url(); it generates incorrectly formatted URLs.
"createdAt": string (timestamp)
"reparseSkippedReason": string
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string",
"reparseSkippedReason": "Response string"
}
]
```
***
### List Files in a Knowledge Base
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/`
{% hint style="info" %}
For files whose parser is automatically detected by the system, `parserAutoDetection` in the response contains the selected parser, the reason category (`reason`), the numeric facts used for detection (`facts`), and the detection time. It is `null` for files whose parser was selected by the user. For field definitions, when the value is `null`, and how reason categories map to numeric facts, see [Parser Auto-Detection Results](/api/en/preparation/parser-auto-detection.md).
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `fileType` | ❌ | string | Filter by file type, such as pdf, docx, txt, or xlsx |
| `knowledgeBase` | ❌ | string | Knowledge Base ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | Search keywords. Supports multiple conditions separated by spaces. Searchable fields: file ID, filename, label name, Metadata value |
| `status` | ❌ | string | Filter by file status. Available values: initial (initializing), processing (processing), done (completed), deleting (deleting), deleted (deleted), failed (failed) \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |
#### Code Examples
{% tabs %} {% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
'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 error: ' . $e->getMessage();
}
?>
```
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"filename": string // Filename
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, disabled; null when OCR completes
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a user-selected parser, files uploaded before the feature launched, or files queued for re-detection
{
"parser": // Parser selected by auto-detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, vision_unavailable; more categories may be added later. Display a generic message when no matching text is available
"facts": object // Numeric facts for the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (body text character count); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable PDF derivative (displayed in a PDF viewer on the frontend); None for other files.
Generate the URL with the same CustomizedFileFieldSerializer used for the `file` field to ensure a consistent format (including each
storage provider's presign/host rules). Do not use get_absolute_url(), which produces incorrectly formatted URLs.
"createdAt": string (timestamp)
}
]
}
```
**Example Response Values**
```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",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
]
}
```
***
### Get Details of a Specific File
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`
{% hint style="info" %}
For files whose parser is automatically detected by the system, `parserAutoDetection` in the response contains the selected parser, the reason category (`reason`), the numeric facts used for detection (`facts`), and the detection time. It is `null` for files whose parser was selected by the user. For field definitions, when the value is `null`, and how reason categories map to numeric facts, see [Parser Auto-Detection Results](/api/en/preparation/parser-auto-detection.md).
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"filename": string // Filename
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, disabled; null when OCR completes
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a user-selected parser, files uploaded before the feature launched, or files queued for re-detection
{
"parser": // Parser selected by auto-detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, vision_unavailable; more categories may be added later. Display a generic message when no matching text is available
"facts": object // Numeric facts for the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (body text character count); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable PDF derivative (displayed in a PDF viewer on the frontend); None for other files.
Generate the URL with the same CustomizedFileFieldSerializer used for the `file` field to ensure a consistent format (including each
storage provider's presign/host rules). Do not use get_absolute_url(), which produces incorrectly formatted URLs.
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
```
***
### Retrieve the Latest File Failure Reason
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/latest-failed-reason/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", config)
.then(response => {
console.log('Response retrieved successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response retrieved successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response retrieved successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"errorMessage": string
"errorCode"?: string // Machine-readable code of a known failure type (see FAILED_REASON_LOCALIZED_MESSAGES in whizchat/parsers/exceptions.py); the serializer translates it into the request language on read. An empty string means no translation, and error_message is shown as is. (Optional)
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"errorMessage": "Response string",
"errorCode": "Response string",
"createdAt": "Response string"
}
```
***
### Retrieve File Transcription
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/transcription/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"filename": string // File name
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, or off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, or disabled; null when completed
"parserAutoDetection": // Result and reason for automatically selecting a parser for this file; null for files with a user-selected parser, files uploaded before launch, or files queued for re-detection
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, or vision_unavailable; more categories may be added later. Display a generic message if no matching text is available
"facts": object // Numeric facts for the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (body text character count); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable PDF derivative (displayed with the PDF viewer on the frontend); otherwise None.
Generate the URL using the same CustomizedFileFieldSerializer as the `file` field to ensure a consistent format (including each
storage provider's presign/host rules). Do not use get_absolute_url(), which produces an incorrectly formatted URL.
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
```
***
### Update File Information
PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filename | string | Yes | File name |
| file | string (uri) | Yes | File to upload |
| parser | string (uuid) | No | |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
| asrOptions | object | No | Per-file canonical transcription options (languages, prompt, diarization). Empty means no per-file options: provider defaults apply. Completely decoupled from user-defined metadata; never indexed for ... |
**Request Schema Example**
```typescript
{
"filename": string // File name
"file": string (uri) // File to upload
"parser"?: string (uuid) // Optional
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
"asrOptions"?: object // Per-file canonical transcription options (languages, prompt, diarization). Empty means no per-file options: provider defaults apply. Completely decoupled from user-defined metadata; never indexed for search. (Optional)
}
```
**Example Request Values**
```json
{
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None,
"asrOptions": None
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'filename' => 'document.pdf',
'file' => 'https://example.com/file.jpg',
'parser' => '550e8400-e29b-41d4-a716-446655440000',
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null,
'asrOptions' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"filename": string // File name
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, or off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, or disabled; null when completed
"parserAutoDetection": // Result and reason for automatically selecting a parser for this file; null for files with a user-selected parser, files uploaded before launch, or files queued for re-detection
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, or vision_unavailable; more categories may be added later. Display a generic message if no matching text is available
"facts": object // Numeric facts for the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (body text character count); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a previewable PDF derivative (displayed with the PDF viewer on the frontend); otherwise None.
Generate the URL using the same CustomizedFileFieldSerializer as the `file` field to ensure a consistent format (including each
storage provider's presign/host rules). Do not use get_absolute_url(), which produces an incorrectly formatted URL.
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
```
***
### Partially Update a File
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filename | string | No | File name |
| file | string (uri) | No | File to upload |
| parser | string (uuid) | No | |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
| asrOptions | object | No | Per-file canonical transcription options (languages, prompt, diarization). Empty means no per-file options: provider defaults apply. Completely decoupled from user-defined metadata; never indexed for ... |
**Request Schema Example**
```typescript
{
"filename"?: string // File name (Optional)
"file"?: string (uri) // File to upload (Optional)
"parser"?: string (uuid) // Optional
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
"asrOptions"?: object // Per-file canonical transcription options (languages, prompt, diarization). Empty means no per-file options: provider defaults apply. Completely decoupled from user-defined metadata; never indexed for search. (Optional)
}
```
**Example Request Values**
```json
{
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null,
"asrOptions": null
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"parser": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None,
"asrOptions": None
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'filename' => 'document.pdf',
'file' => 'https://example.com/file.jpg',
'parser' => '550e8400-e29b-41d4-a716-446655440000',
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null,
'asrOptions' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"filename": string // File name
"file": string (uri) // File to upload
"fileType": string
"knowledgeBase"?: // Optional
{
"id": string (uuid)
"name": string
}
"size": integer // File size in bytes
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (Optional)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"ocrStatus": string // OCR result for scanned pages: done, skipped, partial, or off; null before parsing or for older files
"ocrSkippedReason": string // Reason OCR was not performed on scanned pages: no_azure_settings, azure_unavailable, insufficient_credits, transient_error, time_budget, or disabled; null when OCR is completed
"parserAutoDetection": // Result and reason for automatic parser selection for this file; null for files with a user-selected parser, files uploaded before this feature launched, or files queued for reassessment
{
"parser": // Parser selected by automatic detection
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"reason": string // Reason category: scanned, image_pages, large_images, unmeasurable_images, presentation, no_image_content, below_threshold, no_content, file_type_not_detected, detection_failed, or vision_unavailable; more categories may be added, so display a generic message when no matching text is available
"facts": object // Numeric values supporting the reason (calculated at detection time and not recalculated later). PDF: analyzed_pages (number of pages examined), partial (whether only the first few pages were examined), non_blank_pages, scanned_pages, image_pages (pages requiring image-based interpretation); Word: figures (number of large images in the body), text_chars (number of characters in the body); an empty object in other cases
"detectedAt": string (timestamp) // Detection time
}
"previewUrl": string // For presentations (pptx/ppt), returns the URL of a derived PDF for preview (displayed with a PDF viewer on the frontend); None for other file types.
Generate the URL with the same CustomizedFileFieldSerializer used for the `file` field to ensure consistent formatting (including each
storage provider's presign/host rules). Do not use get_absolute_url(), which produces an incorrectly formatted URL.
"createdAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"file": "https://example.com/file.jpg",
"fileType": "Response string",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "Response string",
"customName": "Response string",
"displayName": "Response string"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"ocrStatus": "Response string",
"ocrSkippedReason": "Response string",
"parserAutoDetection": {
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"provider": {},
"isTimestampSttProvider": false
},
"reason": "Response string",
"facts": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
},
"detectedAt": "Response string"
},
"previewUrl": "Response string",
"createdAt": "Response string"
}
```
***
### Delete a File
DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base File. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
'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: 202**
**Example Response Schema**
```typescript
{
"detail": string
}
```
**Example Response Values**
```json
{
"detail": "response string"
}
```
**Status Code: 204 - No response body**
***
### Create a File Translation
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`
#### Parameters
| Parameter name | Required | Type | Description |
| --------------------- | -------- | ------ | ----------- |
| `knowledgeBaseFilePk` | ✅ | string | |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| -------------------- | ------------- | -------- | ----------- |
| sourceLanguage | string | No | |
| targetLanguage | string | Yes | |
| customPrompt | string | No | |
| largeLanguageModelId | string (uuid) | Yes | |
**Example request schema**
```typescript
{
"sourceLanguage"?: string // Optional
"targetLanguage": string
"customPrompt"?: string // Optional
"largeLanguageModelId": string (uuid)
}
```
**Example request values**
```json
{
"sourceLanguage": "Example string",
"targetLanguage": "Example string",
"customPrompt": "Example string",
"largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sourceLanguage": "Example string",
"targetLanguage": "Example string",
"customPrompt": "Example string",
"largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"sourceLanguage": "Example string",
"targetLanguage": "Example string",
"customPrompt": "Example string",
"largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"sourceLanguage": "Example string",
"targetLanguage": "Example string",
"customPrompt": "Example string",
"largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'sourceLanguage' => 'Example string',
'targetLanguage' => 'Example string',
'customPrompt' => 'Example string',
'largeLanguageModelId' => '550e8400-e29b-41d4-a716-446655440000'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 201**
**Example response schema**
```typescript
{
"sourceLanguage"?: string // Optional
"targetLanguage": string
"customPrompt"?: string // Optional
"largeLanguageModelId": string (uuid)
}
```
**Example response values**
```json
{
"sourceLanguage": "Response string",
"targetLanguage": "Response string",
"customPrompt": "Response string",
"largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### List File Translations
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`
#### Parameters
| Parameter name | Required | Type | Description |
| --------------------- | -------- | ------- | ---------------------------------------------- |
| `knowledgeBaseFilePk` | ✅ | string | |
| `knowledgeBasePk` | ✅ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"chatbotFileId": string (uuid)
"chatbotFileFilename": string
"organization": string (uuid)
"largeLanguageModel":
{
"id": string (uuid)
"name": string
}
"sourceLanguage": string
"targetLanguage": string
"customPrompt": string // User-provided terminology/glossary rules
"status":
{
}
"errorMessage": string
"translatedFileUrl": string
"bilingualFileUrl": string
"processDuration": string
"processingDurationSeconds": number (double)
"pageCount": integer
"originalWordCount": integer
"translatedWordCount": integer
"inputTokensUsed": integer
"outputTokensUsed": integer
"totalTokensUsed": integer
"originalFileSize": integer
"translatedFileSize": integer
"bilingualFileSize": integer
"llmTranslationDuration": string // Total time spent on LLM API calls
"llmTranslationDurationSeconds": number (double)
"llmCallCount": integer // Number of LLM API calls made
"avgLlmCallDuration": number (double) // Average time per LLM call in seconds
"pdfParsingDuration": string // Time spent on PDF parsing and processing
"pdfParsingDurationSeconds": number (double)
"fileSavingDuration": string // Time spent on saving output files
"fileSavingDurationSeconds": number (double)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example response values**
```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",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileFilename": "Response string",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"sourceLanguage": "Response string",
"targetLanguage": "Response string",
"customPrompt": "Response string",
"status": {},
"errorMessage": "Response string",
"translatedFileUrl": "Response string",
"bilingualFileUrl": "Response string",
"processDuration": "Response string",
"processingDurationSeconds": 456,
"pageCount": 456,
"originalWordCount": 456,
"translatedWordCount": 456,
"inputTokensUsed": 456,
"outputTokensUsed": 456,
"totalTokensUsed": 456,
"originalFileSize": 456,
"translatedFileSize": 456,
"bilingualFileSize": 456,
"llmTranslationDuration": "Response string",
"llmTranslationDurationSeconds": 456,
"llmCallCount": 456,
"avgLlmCallDuration": 456,
"pdfParsingDuration": "Response string",
"pdfParsingDurationSeconds": 456,
"fileSavingDuration": "Response string",
"fileSavingDurationSeconds": 456,
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Retrieve a Specific Translation
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| --------------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this File Translation. |
| `knowledgeBaseFilePk` | ✅ | string | |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"chatbotFileId": string (uuid)
"chatbotFileFilename": string
"organization": string (uuid)
"largeLanguageModel":
{
"id": string (uuid)
"name": string
}
"sourceLanguage": string
"targetLanguage": string
"customPrompt": string // User-provided terminology/glossary rules
"status":
{
}
"errorMessage": string
"translatedFileUrl": string
"bilingualFileUrl": string
"processDuration": string
"processingDurationSeconds": number (double)
"pageCount": integer
"originalWordCount": integer
"translatedWordCount": integer
"inputTokensUsed": integer
"outputTokensUsed": integer
"totalTokensUsed": integer
"originalFileSize": integer
"translatedFileSize": integer
"bilingualFileSize": integer
"llmTranslationDuration": string // Total time spent on LLM API calls
"llmTranslationDurationSeconds": number (double)
"llmCallCount": integer // Number of LLM API calls made
"avgLlmCallDuration": number (double) // Average time per LLM call in seconds
"pdfParsingDuration": string // Time spent on PDF parsing and processing
"pdfParsingDurationSeconds": number (double)
"fileSavingDuration": string // Time spent on saving output files
"fileSavingDurationSeconds": number (double)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileFilename": "Response string",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"sourceLanguage": "Response string",
"targetLanguage": "Response string",
"customPrompt": "Response string",
"status": {},
"errorMessage": "Response string",
"translatedFileUrl": "Response string",
"bilingualFileUrl": "Response string",
"processDuration": "Response string",
"processingDurationSeconds": 456,
"pageCount": 456,
"originalWordCount": 456,
"translatedWordCount": 456,
"inputTokensUsed": 456,
"outputTokensUsed": 456,
"totalTokensUsed": 456,
"originalFileSize": 456,
"translatedFileSize": 456,
"bilingualFileSize": 456,
"llmTranslationDuration": "Response string",
"llmTranslationDurationSeconds": 456,
"llmCallCount": 456,
"avgLlmCallDuration": 456,
"pdfParsingDuration": "Response string",
"pdfParsingDurationSeconds": 456,
"fileSavingDuration": "Response string",
"fileSavingDurationSeconds": 456,
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Delete a Translation
DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| --------------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this File Translation. |
| `knowledgeBaseFilePk` | ✅ | string | |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Download a Translated File
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/download/`
#### Parameters
| Parameter name | Required | Type | Description |
| --------------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this File Translation. |
| `knowledgeBaseFilePk` | ✅ | string | |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"chatbotFileId": string (uuid)
"chatbotFileFilename": string
"organization": string (uuid)
"largeLanguageModel":
{
"id": string (uuid)
"name": string
}
"sourceLanguage": string
"targetLanguage": string
"customPrompt": string // User-provided terminology/glossary rules
"status":
{
}
"errorMessage": string
"translatedFileUrl": string
"bilingualFileUrl": string
"processDuration": string
"processingDurationSeconds": number (double)
"pageCount": integer
"originalWordCount": integer
"translatedWordCount": integer
"inputTokensUsed": integer
"outputTokensUsed": integer
"totalTokensUsed": integer
"originalFileSize": integer
"translatedFileSize": integer
"bilingualFileSize": integer
"llmTranslationDuration": string // Total time spent on LLM API calls
"llmTranslationDurationSeconds": number (double)
"llmCallCount": integer // Number of LLM API calls made
"avgLlmCallDuration": number (double) // Average time per LLM call in seconds
"pdfParsingDuration": string // Time spent on PDF parsing and processing
"pdfParsingDurationSeconds": number (double)
"fileSavingDuration": string // Time spent on saving output files
"fileSavingDurationSeconds": number (double)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileFilename": "Response string",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"sourceLanguage": "Response string",
"targetLanguage": "Response string",
"customPrompt": "Response string",
"status": {},
"errorMessage": "Response string",
"translatedFileUrl": "Response string",
"bilingualFileUrl": "Response string",
"processDuration": "Response string",
"processingDurationSeconds": 456,
"pageCount": 456,
"originalWordCount": 456,
"translatedWordCount": 456,
"inputTokensUsed": 456,
"outputTokensUsed": 456,
"totalTokensUsed": 456,
"originalFileSize": 456,
"translatedFileSize": 456,
"bilingualFileSize": 456,
"llmTranslationDuration": "Response string",
"llmTranslationDurationSeconds": 456,
"llmCallCount": 456,
"avgLlmCallDuration": 456,
"pdfParsingDuration": "Response string",
"pdfParsingDurationSeconds": 456,
"fileSavingDuration": "Response string",
"fileSavingDurationSeconds": 456,
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### List Knowledge Base Documents
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/`
#### Parameters
| Parameter Name | Required | Type | Description |
| --------------------- | -------- | ------ | ----------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `chatbotFileId` | ❌ | string | \[To be deprecated] File ID (use knowledge\_base\_file\_id) |
| `knowledgeBaseFileId` | ❌ | string | Knowledge Base File ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Configure request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example", config)
.then(response => {
console.log('Response retrieved successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response retrieved successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response retrieved successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
[
{
"id": string (uuid)
"fileName": string
"pageNumber"?: integer // Optional
"chatbotFile": string (uuid)
"excludedEmbedMetadataKeys"?: object // List[str]: metadata keys to exclude from the embedding. (Optional)
"excludedLlmMetadataKeys"?: object // List[str]: metadata keys to exclude from the LLM context. (Optional)
"llamaIndexObjectJson"?: object // Optional
"metadata"?: object // Optional
"text": string
"updatedAt": string (timestamp)
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "Response string",
"pageNumber": 456,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "Response string",
"updatedAt": "Response string"
}
]
```
**Status Code: 404 - The knowledge base file does not exist or does not belong to the current organization**
***
### Update a Document
PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot Document. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ------------------------- | ------------- | -------- | ---------------------------------------------------------- |
| fileName | string | Yes | |
| pageNumber | integer | No | |
| chatbotFile | string (uuid) | Yes | |
| excludedEmbedMetadataKeys | object | No | List\[str]: metadata keys to exclude from the embedding. |
| excludedLlmMetadataKeys | object | No | List\[str]: metadata keys to exclude from the LLM context. |
| llamaIndexObjectJson | object | No | |
| metadata | object | No | |
| text | string | Yes | |
**Example Request Schema**
```typescript
{
"fileName": string
"pageNumber"?: integer // Optional
"chatbotFile": string (uuid)
"excludedEmbedMetadataKeys"?: object // List[str]: metadata keys to exclude from the embedding. (Optional)
"excludedLlmMetadataKeys"?: object // List[str]: metadata keys to exclude from the LLM context. (Optional)
"llamaIndexObjectJson"?: object // Optional
"metadata"?: object // Optional
"text": string
}
```
**Example Request Values**
```json
{
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Configure request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request Body (payload)
const data = {
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response retrieved successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": None,
"excludedLlmMetadataKeys": None,
"llamaIndexObjectJson": None,
"metadata": None,
"text": "This is an example message"
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response retrieved successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'fileName' => 'Example string',
'pageNumber' => 123,
'chatbotFile' => '550e8400-e29b-41d4-a716-446655440000',
'excludedEmbedMetadataKeys' => null,
'excludedLlmMetadataKeys' => null,
'llamaIndexObjectJson' => null,
'metadata' => null,
'text' => 'This is an example message'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response retrieved successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"fileName": string
"pageNumber"?: integer // Optional
"chatbotFile": string (uuid)
"excludedEmbedMetadataKeys"?: object // List[str]: metadata keys to exclude from the embedding. (Optional)
"excludedLlmMetadataKeys"?: object // List[str]: metadata keys to exclude from the LLM context. (Optional)
"llamaIndexObjectJson"?: object // Optional
"metadata"?: object // Optional
"text": string
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "Response string",
"pageNumber": 456,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "Response string",
"updatedAt": "Response string"
}
```
***
### Partially Update a Document
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot Document. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| ------------------------- | ------------- | -------- | ---------------------------------------------------------- |
| fileName | string | No | |
| pageNumber | integer | No | |
| chatbotFile | string (uuid) | No | |
| excludedEmbedMetadataKeys | object | No | List\[str]: metadata keys to exclude from the embedding. |
| excludedLlmMetadataKeys | object | No | List\[str]: metadata keys to exclude from the LLM context. |
| llamaIndexObjectJson | object | No | |
| metadata | object | No | |
| text | string | No | |
**Example Request Schema**
```typescript
{
"fileName"?: string // Optional
"pageNumber"?: integer // Optional
"chatbotFile"?: string (uuid) // Optional
"excludedEmbedMetadataKeys"?: object // List[str]: metadata keys to exclude from the embedding. (Optional)
"excludedLlmMetadataKeys"?: object // List[str]: metadata keys to exclude from the LLM context. (Optional)
"llamaIndexObjectJson"?: object // Optional
"metadata"?: object // Optional
"text"?: string // Optional
}
```
**Example Request Values**
```json
{
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Configure request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request Body (payload)
const data = {
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "This is an example message"
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response retrieved successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"fileName": "Example string",
"pageNumber": 123,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": None,
"excludedLlmMetadataKeys": None,
"llamaIndexObjectJson": None,
"metadata": None,
"text": "This is an example message"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response retrieved successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'fileName' => 'Example string',
'pageNumber' => 123,
'chatbotFile' => '550e8400-e29b-41d4-a716-446655440000',
'excludedEmbedMetadataKeys' => null,
'excludedLlmMetadataKeys' => null,
'llamaIndexObjectJson' => null,
'metadata' => null,
'text' => 'This is an example message'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response retrieved successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request failed: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"fileName": string
"pageNumber"?: integer // Optional
"chatbotFile": string (uuid)
"excludedEmbedMetadataKeys"?: object // List[str]: metadata keys to exclude from the embedding. (Optional)
"excludedLlmMetadataKeys"?: object // List[str]: metadata keys to exclude from the LLM context. (Optional)
"llamaIndexObjectJson"?: object // Optional
"metadata"?: object // Optional
"text": string
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"fileName": "Response string",
"pageNumber": 456,
"chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
"excludedEmbedMetadataKeys": null,
"excludedLlmMetadataKeys": null,
"llamaIndexObjectJson": null,
"metadata": null,
"text": "Response string",
"updatedAt": "Response string"
}
```
***
### Delete a Document
DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot Document. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Configure request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request Body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response retrieved successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request failed:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response retrieved successfully:")
print(response.json())
except Exception as e:
print("Request failed:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Create a new FAQ
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------- |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | -------------------------------------------------------------- |
| question | string | Yes | |
| answer | string | Yes | |
| answerMediaUrls | object | No | URLs of media files, such as images and videos, in the answer. |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
**Example request schema**
```typescript
{
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
}
```
**Example request values**
```json
{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": None,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => 'Example string',
'answer' => 'Example string',
'answerMediaUrls' => null,
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 201**
**Example response schema**
```typescript
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
```
***
### Update FAQ metadata
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/update-metadata/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------------------------------- |
| `id` | ✅ | string | A UUID string identifying this FAQ. |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | ----------- |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
**Example request schema**
```typescript
{
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
}
```
**Example request values**
```json
{
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/update-metadata/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/update-metadata/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/update-metadata/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/update-metadata/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
```
**Example response values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
```
***
### Batch delete FAQs
POST `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------- |
| `knowledgeBasePk` | ✅ | string | |
#### Request body
**Request parameters**
| Field | Type | Required | Description |
| ----- | -------------- | -------- | ----------- |
| ids | array\[string] | No | |
**Example request schema**
```typescript
{
"ids"?: [ // Optional
string (uuid)
]
}
```
**Example request values**
```json
{
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 body (payload)
const data = {
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'ids' => [
'550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### List all FAQs in a specific knowledge base
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | Search keywords. Supports multiple search criteria separated by spaces. Searchable fields: FAQ ID, question, answer, label name, and Metadata value |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
]
}
```
**Example response values**
```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",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
]
}
```
***
### Retrieve details of a specific FAQ
GET `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`
#### Parameters
| Parameter name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------------------------------- |
| `id` | ✅ | string | A UUID string identifying this FAQ. |
| `knowledgeBasePk` | ✅ | string | |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
```
***
### Update FAQ
PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------------------------------- |
| `id` | ✅ | string | A UUID string identifying this FAQ. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | -------------------------------------------------------------- |
| question | string | Yes | |
| answer | string | Yes | |
| answerMediaUrls | object | No | URLs of media files, such as images and videos, in the answer. |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
**Example Request Schema**
```typescript
{
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
}
```
**Example Request Values**
```json
{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
};
axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": None,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => 'Example string',
'answer' => 'Example string',
'answerMediaUrls' => null,
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
```
***
### Partially Update FAQ
PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------------------------------- |
| `id` | ✅ | string | A UUID string identifying this FAQ. |
| `knowledgeBasePk` | ✅ | string | |
#### Request Body
**Request Parameters**
| Field | Type | Required | Description |
| --------------------- | -------------- | -------- | -------------------------------------------------------------- |
| question | string | No | |
| answer | string | No | |
| answerMediaUrls | object | No | URLs of media files, such as images and videos, in the answer. |
| labels | array\[IdName] | No | |
| rawUserDefineMetadata | object | No | |
**Example Request Schema**
```typescript
{
"question"?: string // Optional
"answer"?: string // Optional
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"labels"?: [ // Optional
{
"id": string (uuid)
}
]
"rawUserDefineMetadata"?: object // Optional
}
```
**Example Request Values**
```json
{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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 Body (payload)
const data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": null,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": null
};
axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request Body (payload)
data = {
"question": "Example string",
"answer": "Example string",
"answerMediaUrls": None,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"rawUserDefineMetadata": None
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => 'Example string',
'answer' => 'Example string',
'answerMediaUrls' => null,
'labels' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
],
'rawUserDefineMetadata' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"question": string
"answer": string
"answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (Optional)
"hitsCount": integer
"embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
"labels"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // Optional
"knowledgeBase": // Always taken from the knowledge base in the URL; a value in the request body is ignored.
{
"id": string (uuid)
"name": string
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"question": "Response string",
"answer": "Response string",
"answerMediaUrls": null,
"hitsCount": 456,
"embeddingTokensCount": 456,
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
],
"rawUserDefineMetadata": null,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
```
***
### Delete FAQ
DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ----------------- | -------- | ------ | ----------------------------------- |
| `id` | ✅ | string | A UUID string identifying this FAQ. |
| `knowledgeBasePk` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request Body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
| Status Code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Export FAQ Excel (or a Blank Template)
GET `/api/v1/knowledge-bases/{id}/export-faq-excel/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-faq-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-faq-excel/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-faq-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-faq-excel/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"createdBy":
{
"id": string (uuid)
"name": string
}
"organization"?: string (uuid) // Optional
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // Optional
"numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional)
"enableHyde"?: boolean // Enable HyDE; defaults to False (Optional)
"similarityCutoff"?: number (double) // Similarity threshold; defaults to 0.0, with a range of 0.0-1.0 (Optional)
"enableRerank"?: boolean // Whether to enable reranking; defaults to True (Optional)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (Optional)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (Optional)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (Optional)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (Optional)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (Optional)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (Optional)
"oracleUser"?: string // Oracle database username. (Optional)
"oraclePassword"?: string // Oracle database password. (Optional)
"synxdbUser"?: string // SynxDB database username. (Optional)
"synxdbPassword"?: string // SynxDB database password. (Optional)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // Optional
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // List of groups that can access the knowledge base (Optional)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "response string"
},
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "response string",
"description": "response string",
"numberOfRetrievedChunks": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "response string",
"vectorDatabaseApiKey": "response string",
"opensearchUsername": "response string",
"opensearchPassword": "response string",
"oracleUser": "response string",
"oraclePassword": "response string",
"synxdbUser": "response string",
"synxdbPassword": "response string",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "response string"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "response string"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "response string"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"canUpdate": false,
"canDelete": false,
"createdAt": "response string",
"updatedAt": "response string"
}
```
***
### Import FAQ Excel (Asynchronous)
POST `/api/v1/knowledge-bases/{id}/import-faq-excel/`
{% hint style="info" %}
Only one import job can run at a time for a knowledge base. Calling this endpoint while a job is running returns `409`; use the FAQ import job endpoints below to check progress.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-faq-excel/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "excelFile=@example_file.txt"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// Create a FormData object
const formData = new FormData();
// Replace with the actual file
formData.append('excelFile', /* Actual file object */, 'example_file.txt');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-faq-excel/", formData, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-faq-excel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# Create file and form data
files = {
'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}
response = requests.post(url, files=files, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-faq-excel/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'excelFile',
'contents' => fopen('example_file.txt', 'r'),
'filename' => 'example_file.txt'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 202**
**Example Response Schema**
```typescript
{
"jobId": string (uuid)
"status": string (enum: pending, processing, done, failed) // * `pending` - Pending
* `processing` - Processing
* `done` - Done
* `failed` - Failed
}
```
**Example Response Values**
```json
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending"
}
```
**Status Code: 409**
**Example Response Schema**
```typescript
{
"detail": string
"jobId": string (uuid)
}
```
**Example Response Values**
```json
{
"detail": "response string",
"jobId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### List FAQ Import Jobs
GET `/api/v1/knowledge-bases/{id}/faq-import-jobs/`
#### Parameters
| Parameter Name | Required | Type | Description |
| ---------------- | -------- | ------- | ---------------------------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
| `embeddingModel` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `pagination` | ❌ | boolean | Set to false to return all jobs without pagination (defaults to true). |
| `query` | ❌ | string | |
| `rerankerModel` | ❌ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=true&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=true&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=true&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=true&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"status":
{
}
"totalRows": integer
"processedRows": integer
"createdCount": integer
"skippedDuplicateCount": integer // Rows skipped because their whitespace-normalized question already exists in the knowledge base or appears earlier in the same file.
"errors": object // Row-level parse errors and chunk-level import errors.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```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",
"status": {},
"totalRows": 456,
"processedRows": 456,
"createdCount": 456,
"skippedDuplicateCount": 456,
"errors": null,
"createdAt": "response string",
"updatedAt": "response string"
}
]
}
```
***
### Retrieve a Specific FAQ Import Job
GET `/api/v1/knowledge-bases/{id}/faq-import-jobs/{jobId}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Knowledge Base. |
| `jobId` | ✅ | string | |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/{jobId}/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/{jobId}/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/{jobId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faq-import-jobs/{jobId}/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"status":
{
}
"totalRows": integer
"processedRows": integer
"createdCount": integer
"skippedDuplicateCount": integer // Rows skipped because their whitespace-normalized question already exists in the knowledge base or appears earlier in the same file.
"errors": object // Row-level parse errors and chunk-level import errors.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": {},
"totalRows": 456,
"processedRows": 456,
"createdCount": 456,
"skippedDuplicateCount": 456,
"errors": null,
"createdAt": "response string",
"updatedAt": "response string"
}
```
***
### List Parsers
GET `/api/v1/parsers/`
{% hint style="info" %}
When uploading a file to a knowledge base, set the `parser` field to the parser `id` returned by this endpoint.
{% endhint %}
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/parsers/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/parsers/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/parsers/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/parsers/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
[
{
"id": string (uuid)
"name": string
"description": string
"provider":
{
}
"order"?: integer // Optional
"isTimestampSttProvider": boolean
"asrProvider": object // The provider spec, built once per provider row per response.
The spec is platform-level, not per parser, and it is large — a
whisper-family row carries a 100-entry language catalog in its
``languages`` spec, as codes plus display names. This serializer is
nested per row in the knowledge-base file listing and in message
citations, so without memoizing, one response rebuilds the same
catalog for every row. ``self.context`` is the root serializer's shared
dict, which is also what keeps ``get_active_diarization_rows`` at one
query per response.
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"provider": {},
"order": 456,
"isTimestampSttProvider": false,
"asrProvider": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
}
}
]
```
***
### Retrieve a Specific Parser
GET `/api/v1/parsers/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | -------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this parser. |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/parsers/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% 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/v1/parsers/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/parsers/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/parsers/550e8400-e29b-41d4-a716-446655440000/", [
'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 error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status Code: 200**
**Example Response Schema**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"provider":
{
}
"order"?: integer // Optional
"isTimestampSttProvider": boolean
"asrProvider": object // The provider spec, built once per provider row per response.
The spec is platform-level, not per parser, and it is large — a
whisper-family row carries a 100-entry language catalog in its
``languages`` spec, as codes plus display names. This serializer is
nested per row in the knowledge-base file listing and in message
citations, so without memoizing, one response rebuilds the same
catalog for every row. ``self.context`` is the root serializer's shared
dict, which is also what keeps ``get_active_diarization_rows`` at one
query per response.
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"provider": {},
"order": 456,
"isTimestampSttProvider": false,
"asrProvider": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example response name",
"description": "Example response description"
}
}
```
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/en/api-reference/zhi-shi-ku-xin-ban.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.