> 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-jiu-ban.md).

# Knowledge Bases (Legacy)

### List Knowledge Base Files for an AI Assistant <a href="#chatbots-knowledge-bases-files-list" id="chatbots-knowledge-bases-files-list"></a>

GET `/api/v1/chatbots/{id}/knowledge-bases-files/`

#### Parameters

| Parameter Name       | Required | Type    | Description                                                                                                                                                                          |
| -------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                 | ✅        | string  |                                                                                                                                                                                      |
| `createdByMember`    | ❌        | string  | Creator filter: the id of a member in this organization (the id returned by the member directory, including deactivated members). Returns only AI assistants created by that member. |
| `largeLanguageModel` | ❌        | string  |                                                                                                                                                                                      |
| `page`               | ❌        | integer | A page number within the paginated result set.                                                                                                                                       |
| `pageSize`           | ❌        | integer | Number of results to return per page.                                                                                                                                                |
| `query`              | ❌        | string  |                                                                                                                                                                                      |
| `replyMode`          | ❌        | string  |                                                                                                                                                                                      |
| `source`             | ❌        | string  | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all;                                                                                                              |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-files/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all" \
  -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/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-files/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-files/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all"
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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-files/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", [
        '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)
      "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 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 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 later, so display a generic message when no matching text is available
        "facts": object // Numeric facts supporting the reason (calculated at assessment 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 visual 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) // Assessment time
      }
      "previewUrl": string // For presentations (pptx/ppt), returns the URL of a derived pdf file for preview (displayed using the 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 an incorrectly formatted URL.
      "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"
    }
  ]
}
```

***

### List Knowledge Base FAQs for an AI Assistant <a href="#chatbots-knowledge-bases-faqs-list" id="chatbots-knowledge-bases-faqs-list"></a>

GET `/api/v1/chatbots/{id}/knowledge-bases-faqs/`

#### Parameters

| Parameter Name       | Required | Type    | Description                                                                                                                                                                       |
| -------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | ✅        | string  |                                                                                                                                                                                   |
| `createdByMember`    | ❌        | string  | Creator filter: the ID of a member in this organization (the ID returned by the member roster, including deactivated members). Returns only AI assistants created by that member. |
| `largeLanguageModel` | ❌        | string  |                                                                                                                                                                                   |
| `page`               | ❌        | integer | A page number within the paginated result set.                                                                                                                                    |
| `pageSize`           | ❌        | integer | Number of results to return per page.                                                                                                                                             |
| `query`              | ❌        | string  |                                                                                                                                                                                   |
| `replyMode`          | ❌        | string  |                                                                                                                                                                                   |
| `source`             | ❌        | string  | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all;                                                                                                           |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-faqs/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all" \
  -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/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-faqs/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-faqs/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all"
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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/knowledge-bases-faqs/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", [
        '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)
      "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 text nodes from all files for an AI assistant <a href="#chatbot-text-nodes-list" id="chatbot-text-nodes-list"></a>

GET `/api/v1/chatbot-text-nodes/`

#### Parameters

| Parameter name      | Required | Type    | Description                                                     |
| ------------------- | -------- | ------- | --------------------------------------------------------------- |
| `chatbotFile`       | ❌        | string  | \[To be deprecated] Chatbot file ID (use knowledge\_base\_file) |
| `knowledgeBaseFile` | ❌        | string  | Knowledge base file ID (recommended)                            |
| `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/chatbot-text-nodes/?chatbotFile=example&knowledgeBaseFile=example&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/chatbot-text-nodes/?chatbotFile=example&knowledgeBaseFile=example&page=1&pageSize=1", 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/chatbot-text-nodes/?chatbotFile=example&knowledgeBaseFile=example&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 failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbot-text-nodes/?chatbotFile=example&knowledgeBaseFile=example&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 failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response content

**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 complete ChatbotFile information, including the file URL and type, to support image previews in the frontend
      "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 images are present (check the file type or Markdown images in text)
      "imageUrl": string // Extract the image URL (use the file URL if available; 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 ``<mark>`` 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
    }
  ]
}
```

**Status code: 403 - You do not have permission to read text nodes from this file: knowledge base files require chatbot\_knowledge\_base\_access and group access to the knowledge base; conversation attachments require chatbot\_chatbot\_access for the assistant; inbox files require group access to the inbox**

**Status code: 404 - The knowledge base file does not exist or does not belong to the current organization**

***

### Retrieve a text node from a specific file for an AI assistant <a href="#chatbot-text-nodes-retrieve" id="chatbot-text-nodes-retrieve"></a>

GET `/api/v1/chatbot-text-nodes/{id}/`

#### Parameters

| Parameter name | Required | Type   | Description                                     |
| -------------- | -------- | ------ | ----------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this ChatbotTextNode. |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbot-text-nodes/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/chatbot-text-nodes/550e8400-e29b-41d4-a716-446655440000/", 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/chatbot-text-nodes/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 failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbot-text-nodes/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 content

**Status code: 200**

**Example response schema**

```typescript
{
  "id": string (uuid)
  "charactersCount": integer
  "hitsCount": integer
  "text": string
  "updatedAt": string (timestamp)
  "filename": string
  "chatbotFile": object // Return complete ChatbotFile information, including the file URL and type, to support image previews in the frontend
  "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 images are present (check the file type or Markdown images in text)
  "imageUrl": string // Extract the image URL (use the file URL if available; 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 ``<mark>`` 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
{
  "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
}
```

***

### Search Test <a href="#chatbots-search-create" id="chatbots-search-create"></a>

POST `/api/v1/chatbots/{id}/search/`

#### Parameters

| Parameter Name       | Required | Type    | Description                                                                                                                                                                       |
| -------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | ✅        | string  |                                                                                                                                                                                   |
| `createdByMember`    | ❌        | string  | Creator filter: the ID of a member of this organization (the ID returned by the member roster, including deactivated members). Returns only AI assistants created by that member. |
| `largeLanguageModel` | ❌        | string  |                                                                                                                                                                                   |
| `page`               | ❌        | integer | A page number within the paginated result set.                                                                                                                                    |
| `pageSize`           | ❌        | integer | Number of results to return per page.                                                                                                                                             |
| `query`              | ❌        | string  |                                                                                                                                                                                   |
| `replyMode`          | ❌        | string  |                                                                                                                                                                                   |
| `source`             | ❌        | string  | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all;                                                                                                           |

#### Request Body

**Request Parameters**

| Field         | Type   | Required | Description                                                           |
| ------------- | ------ | -------- | --------------------------------------------------------------------- |
| queryMetadata | object | No       | Not supported for chatbot-wide search; providing a value returns 400. |

**Example Request Schema**

```typescript
{
  "queryMetadata"?: object // Not supported for chatbot-wide search; providing a value returns 400. (Optional)
}
```

**Example Request Values**

```json
{
  "queryMetadata": null
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/search/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Example string",
    "queryMetadata": 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 = {
    "query": "Example string",
    "queryMetadata": null
  };

axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/search/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/search/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request Body (payload)
data = {
    "query": "Example string",
    "queryMetadata": 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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/search/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&replyMode=example&source=all", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'query' => 'Example string',
            'queryMetadata' => 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
{
  "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 // Returns complete ChatbotFile information, including the file URL and type, to support image previews in the frontend.
      "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 // Checks whether images are present (by checking the file type or Markdown images in text).
      "imageUrl": string // Extracts the image URL (uses the file URL first; otherwise extracts it from Markdown).
      "displayText": string // Returns the full text with Markdown image markup removed.
      "displayTitle": string // Returns the display title (fallback: citation_title -> filename).
      "highlightedText": string // Return text with matched terms wrapped in ``<mark>`` 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
    }
  ]
}
```

***

### List parsers supported by file type <a href="#parsers-supported-file-types-list" id="parsers-supported-file-types-list"></a>

GET `/api/v1/parsers/supported-file-types/`

#### Parameters

| Parameter name    | Required | Type   | Description                                                                                                                            |
| ----------------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBaseId` | ❌        | string | Knowledge base ID. When provided and the knowledge base does not support multimodal embeddings, image file types will be filtered out. |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/parsers/supported-file-types/?knowledgeBaseId=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/parsers/supported-file-types/?knowledgeBaseId=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/parsers/supported-file-types/?knowledgeBaseId=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/parsers/supported-file-types/?knowledgeBaseId=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
[
  {
    "fileType": string
    "parsers": [
      {
        "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.
      }
    ]
    "autoDetect": boolean // Whether files of this type get parser auto-detection after upload
(the system auto-detects a parser when the user did not choose one).
  }
]
```

**Example response values**

```json
[
  [
    {
      "fileType": ".pdf",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true,
          "visionTier": null,
          "pricingBasis": "page",
          "creditsPerPage": "13.3",
          "pricingSource": "measured",
          "pricingNote": "Scanned pages incur an additional OCR charge of 19.8 credits/page"
        },
        {
          "id": "6d0f4c5e-2f1a-4c47-9a7e-7f4b8f0c2a11",
          "name": "MaiAgent Vision Parser",
          "provider": "anthropic",
          "order": 1,
          "isDefault": false,
          "visionTier": "high_quality",
          "pricingBasis": "page",
          "creditsPerPage": null,
          "pricingSource": null,
          "pricingNote": "Billed by the amount of page content; the displayed value is the average over the past 30 days"
        },
        {
          "id": "9b1c7d2e-4f3a-4e8b-a6d5-0c2f8e9a7b14",
          "name": "MaiAgent OCR Parser (CPU)",
          "provider": "docling",
          "order": 5,
          "isDefault": false,
          "visionTier": null,
          "pricingBasis": null,
          "creditsPerPage": null,
          "pricingSource": null,
          "pricingNote": null
        },
        {
          "id": "8b2f6d14-0c3e-4a7b-9e51-2d6f8a0c4e97",
          "name": "MaiAgent Vision Parser (Gemma 4 31B)",
          "provider": "anthropic",
          "order": 3,
          "isDefault": false,
          "visionTier": "high_quality",
          "pricingBasis": "page",
          "creditsPerPage": "22.275",
          "pricingSource": "reference",
          "pricingNote": "Reference price; actual charges depend on tokens and the number of OCR pages"
        }
      ]
    },
    {
      "fileType": ".doc",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        },
        {
          "id": "6d0f4c5e-2f1a-4c47-9a7e-7f4b8f0c2a11",
          "name": "MaiAgent Vision Parser",
          "provider": "anthropic",
          "order": 1,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".docx",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        },
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".ppt",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        },
        {
          "id": "6d0f4c5e-2f1a-4c47-9a7e-7f4b8f0c2a11",
          "name": "MaiAgent Vision Parser",
          "provider": "anthropic",
          "order": 1,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".pptx",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        },
        {
          "id": "6d0f4c5e-2f1a-4c47-9a7e-7f4b8f0c2a11",
          "name": "MaiAgent Vision Parser",
          "provider": "anthropic",
          "order": 1,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".xls",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".xlsx",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".csv",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".txt",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".md",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".json",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".jsonl",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".html",
      "parsers": [
        {
          "id": "ab83f144-5026-4bce-993f-5c982cc19318",
          "name": "MaiAgent Parser",
          "provider": "maiagent",
          "order": 0,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".mp3",
      "parsers": [
        {
          "id": "4c47e305-2eb7-4438-8d3c-d91eb0b06cc0",
          "name": "Azure Speech",
          "provider": "azure",
          "order": 1,
          "isDefault": true
        }
      ]
    },
    {
      "fileType": ".wav",
      "parsers": [
        {
          "id": "4c47e305-2eb7-4438-8d3c-d91eb0b06cc0",
          "name": "Azure Speech",
          "provider": "azure",
          "order": 1,
          "isDefault": true
        }
      ]
    }
  ]
]
```

***


---

# 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-jiu-ban.md?ask=<question>&goal=<user_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.