> 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/api-reference/zhi-shi-ku-jiu-ban.md).

# 知識庫（舊版）

### 取得 AI 助理的知識庫檔案列表 <a href="#chatbots-knowledge-bases-files-list" id="chatbots-knowledge-bases-files-list"></a>

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

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `createdByMember`    | ❌  | string  | 建立者篩選：本組織成員 id（成員名冊回傳的 id，含已停用成員），只回該成員建立的 AI 助理                        |
| `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; |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (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"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.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("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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 "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "fileType": string
      "knowledgeBase"?:  // 非必填
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer // File size in bytes
      "status": 
      {
      }
      "parser": 
      {
        "id": string (uuid)
        "name": string
        "provider": string (enum: maiagent, llama, azure, docling, whisper_groq, whisper_openai, whisper_offline, localai, anthropic, bronci, alibaba, rap, vertex, cohere) // * `maiagent` - MaiAgent
* `llama` - Llama
* `azure` - Azure
* `docling` - Docling
* `whisper_groq` - WhisperGroq
* `whisper_openai` - WhisperOpenAI
* `whisper_offline` - WhisperOffline
* `localai` - LocalAI
* `anthropic` - Anthropic
* `bronci` - Bronci
* `alibaba` - Alibaba Qwen
* `rap` - Taiwan AI RAP
* `vertex` - Vertex AI
* `cohere` - Cohere
        "isTimestampSttProvider": boolean
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "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 結果：done、skipped、partial、off；解析前或舊檔案為 null
      "ocrSkippedReason": string // 掃描頁沒做 OCR 的原因：no_azure_settings、azure_unavailable、insufficient_credits、transient_error、time_budget、disabled；有做完時為 null
      "visualAnalysis": object // 影片畫面分析結果：status 為 completed 或 incomplete，reason 是未完成原因（model_error、timeout、video_unreadable、model_not_vision、no_describable_content），frame_cap_reached 表示畫面張數達上限；沒做過畫面分析的檔案為 null
      "parserAutoDetection":  // 自動偵測替這份檔選解析器的結果與原因；使用者自己選的、上線前上傳的、重新判斷排隊中的檔為 null
      {
        "parser":  // 自動偵測選到的解析器
        {
          "id": string (uuid)
          "name": string
          "provider": string (enum: maiagent, llama, azure, docling, whisper_groq, whisper_openai, whisper_offline, localai, anthropic, bronci, alibaba, rap, vertex, cohere) // * `maiagent` - MaiAgent
* `llama` - Llama
* `azure` - Azure
* `docling` - Docling
* `whisper_groq` - WhisperGroq
* `whisper_openai` - WhisperOpenAI
* `whisper_offline` - WhisperOffline
* `localai` - LocalAI
* `anthropic` - Anthropic
* `bronci` - Bronci
* `alibaba` - Alibaba Qwen
* `rap` - Taiwan AI RAP
* `vertex` - Vertex AI
* `cohere` - Cohere
          "isTimestampSttProvider": boolean
        }
        "reason": string // 原因類別：scanned、image_pages、large_images、unmeasurable_images、presentation、no_image_content、below_threshold、no_content、file_type_not_detected、detection_failed、vision_unavailable；之後可能新增類別，沒有對應文案時請顯示通用句
        "facts": object // 原因裡的數字（判斷當下算出，之後不重算）。PDF 與簡報（一張投影片算一頁）：analyzed_pages（判斷看的頁數）、partial（是否只看前面幾頁）、non_blank_pages、scanned_pages、image_pages（需要以圖片判讀的頁）；Word：figures（內文大圖數）、text_chars（內文字數）；其他情況為空物件
        "detectedAt": string (timestamp) // 判斷時間
      }
      "previewUrl": string // 簡報（pptx/ppt）回傳可預覽的 pdf 衍生檔 URL（前端用 PDF 預覽器顯示）；其餘為 None。

用與 `file` 欄位相同的 CustomizedFileFieldSerializer 產 URL，確保格式一致（含各
storage provider 的 presign/host 規則）。不可用 get_absolute_url()——它產出的 URL 格式錯誤。
      "createdAt": string (timestamp)
      "parseQueue":  // 檔案在等 Vision 解析名額時的排隊位置；沒在排隊或沒有排隊資料時為 null（顯示「處理中」）
      {
        "position": integer // 同組織排在前面、目前可以開始的檔案數；0＝下一個就是它；null＝被超大檔同時處理上限擋住
      }
    }
  ]
}
```

**回應範例值**

```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": "回應字串",
      "file": "https://example.com/file.jpg",
      "fileType": "回應字串",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "provider": "maiagent",
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "ocrStatus": "回應字串",
      "ocrSkippedReason": "回應字串",
      "visualAnalysis": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "parserAutoDetection": {
        "parser": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "provider": "maiagent",
          "isTimestampSttProvider": false
        },
        "reason": "回應字串",
        "facts": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "detectedAt": "回應字串"
      },
      "previewUrl": "回應字串",
      "createdAt": "回應字串",
      "parseQueue": {
        "position": 456
      }
    }
  ]
}
```

***

### 取得 AI 助理的知識庫 FAQ 列表 <a href="#chatbots-knowledge-bases-faqs-list" id="chatbots-knowledge-bases-faqs-list"></a>

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

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `createdByMember`    | ❌  | string  | 建立者篩選：本組織成員 id（成員名冊回傳的 id，含已停用成員），只回該成員建立的 AI 助理                        |
| `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; |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (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"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.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("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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 "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "question": string
      "answer": string
      "answerMediaUrls"?: object // URLs of media files, such as images and videos, in the answer. (非必填)
      "hitsCount": integer
      "embeddingTokensCount": integer // Number of embedding tokens used to create this FAQ.
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "knowledgeBase":  // Always taken from the knowledge base in the URL; a value in the request body is ignored.
      {
        "id": string (uuid)
        "name": string
      }
    }
  ]
}
```

**回應範例值**

```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": "回應字串",
      "answer": "回應字串",
      "answerMediaUrls": null,
      "hitsCount": 456,
      "embeddingTokensCount": 456,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      }
    }
  ]
}
```

***

### 取得 AI 助理的所有檔案的文本節點 <a href="#chatbot-text-nodes-list" id="chatbot-text-nodes-list"></a>

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

#### 參數

| 參數名稱                | 必填 | 類型      | 說明                                             |
| ------------------- | -- | ------- | ---------------------------------------------- |
| `chatbotFile`       | ❌  | string  | 【將棄用】Chatbot 檔案 ID（請使用 knowledge\_base\_file）  |
| `knowledgeBaseFile` | ❌  | string  | 知識庫檔案 ID（建議使用）                                 |
| `page`              | ❌  | integer | A page number within the paginated result set. |
| `pageSize`          | ❌  | integer | Number of results to return per page.          |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (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"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    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("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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 "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "charactersCount": integer
      "hitsCount": integer
      "text": string
      "updatedAt": string (timestamp)
      "filename": string
      "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
      "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
      "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 // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
      "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
      "displayText": string // 返回移除圖片 Markdown 標記的完整文字
      "displayTitle": string // 返回顯示標題（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. (非必填)
      "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 // Character offset where this paragraph starts in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
      "endCharIdx": integer // Character offset where this paragraph ends in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "charactersCount": 456,
      "hitsCount": 456,
      "text": "回應字串",
      "updatedAt": "回應字串",
      "filename": "回應字串",
      "chatbotFile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "knowledgeBaseFile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "pageNumber": 456,
      "pageStart": 456,
      "pageEnd": 456,
      "citationTitle": "回應字串",
      "citationDescription": "回應字串",
      "citationQuote": "回應字串",
      "hasImage": false,
      "imageUrl": "回應字串",
      "displayText": "回應字串",
      "displayTitle": "回應字串",
      "highlightedText": "回應字串",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "metadataEnabledForSearch": {
        "key1": "value1",
        "key2": "value2",
        "createdAt": "2025-01-01T00:00:00.000Z"
      },
      "startCharIdx": 456,
      "endCharIdx": 456
    }
  ]
}
```

**狀態碼: 403 - 無權讀取此檔案的文本節點：知識庫檔案需要 chatbot\_knowledge\_base\_access 且群組已授權該知識庫；對話附件需要該助理的 chatbot\_chatbot\_access；收件匣檔案需要群組已授權該收件匣**

**狀態碼: 404 - 知識庫檔案不存在，或不屬於目前組織**

***

### 取得 AI 助理的特定檔案的文本節點 <a href="#chatbot-text-nodes-retrieve" id="chatbot-text-nodes-retrieve"></a>

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

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                              |
| ---- | -- | ------ | ----------------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this ChatbotTextNode. |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (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"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    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("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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 "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "charactersCount": integer
  "hitsCount": integer
  "text": string
  "updatedAt": string (timestamp)
  "filename": string
  "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
  "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
  "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 // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
  "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
  "displayText": string // 返回移除圖片 Markdown 標記的完整文字
  "displayTitle": string // 返回顯示標題（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. (非必填)
  "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 // Character offset where this paragraph starts in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
  "endCharIdx": integer // Character offset where this paragraph ends in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "charactersCount": 456,
  "hitsCount": 456,
  "text": "回應字串",
  "updatedAt": "回應字串",
  "filename": "回應字串",
  "chatbotFile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "knowledgeBaseFile": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "pageNumber": 456,
  "pageStart": 456,
  "pageEnd": 456,
  "citationTitle": "回應字串",
  "citationDescription": "回應字串",
  "citationQuote": "回應字串",
  "hasImage": false,
  "imageUrl": "回應字串",
  "displayText": "回應字串",
  "displayTitle": "回應字串",
  "highlightedText": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "metadataEnabledForSearch": {
    "key1": "value1",
    "key2": "value2",
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "startCharIdx": 456,
  "endCharIdx": 456
}
```

***

### 搜尋測試 <a href="#chatbots-search-create" id="chatbots-search-create"></a>

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

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `createdByMember`    | ❌  | string  | 建立者篩選：本組織成員 id（成員名冊回傳的 id，含已停用成員），只回該成員建立的 AI 助理                        |
| `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; |

#### 請求內容

**請求參數**

| 欄位            | 類型     | 必填 | 說明                                                                    |
| ------------- | ------ | -- | --------------------------------------------------------------------- |
| queryMetadata | object | 否  | Not supported for chatbot-wide search; providing a value returns 400. |

**請求結構範例**

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

**請求範例值**

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (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": "範例字串",
    "queryMetadata": null
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "query": "範例字串",
    "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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.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"
}

# 請求內容 (payload)
data = {
    "query": "範例字串",
    "queryMetadata": None
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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' => '範例字串',
            'queryMetadata' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "charactersCount": integer
      "hitsCount": integer
      "text": string
      "updatedAt": string (timestamp)
      "filename": string
      "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
      "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
      "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 // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
      "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
      "displayText": string // 返回移除圖片 Markdown 標記的完整文字
      "displayTitle": string // 返回顯示標題（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. (非必填)
      "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 // Character offset where this paragraph starts in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
      "endCharIdx": integer // Character offset where this paragraph ends in its file's assembled text. Null inside message citations; a knowledge base file's text-node pages and search results carry a value.
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "charactersCount": 456,
      "hitsCount": 456,
      "text": "回應字串",
      "updatedAt": "回應字串",
      "filename": "回應字串",
      "chatbotFile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "knowledgeBaseFile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "pageNumber": 456,
      "pageStart": 456,
      "pageEnd": 456,
      "citationTitle": "回應字串",
      "citationDescription": "回應字串",
      "citationQuote": "回應字串",
      "hasImage": false,
      "imageUrl": "回應字串",
      "displayText": "回應字串",
      "displayTitle": "回應字串",
      "highlightedText": "回應字串",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "metadataEnabledForSearch": {
        "key1": "value1",
        "key2": "value2",
        "createdAt": "2025-01-01T00:00:00.000Z"
      },
      "startCharIdx": 456,
      "endCharIdx": 456
    }
  ]
}
```

***

### 列出檔案類型支援的解析器 <a href="#parsers-supported-file-types-list" id="parsers-supported-file-types-list"></a>

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

#### 參數

| 參數名稱              | 必填 | 類型     | 說明                                                                                                                                                                                                          |
| ----------------- | -- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBaseId` | ❌  | string | Knowledge base ID. When provided and the knowledge base does not support multimodal embeddings, an image file type lists only the parsers whose OCR can read the picture text now, and is left out unles... |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/parsers/supported-file-types/?knowledgeBaseId=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
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('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.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("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", 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 "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "fileType": string
    "parsers": [
      {
        "id": string (uuid)
        "name": string
        "description": string
        "provider": string (enum: maiagent, llama, azure, docling, whisper_groq, whisper_openai, whisper_offline, localai, anthropic, bronci, alibaba, rap, vertex, cohere) // * `maiagent` - MaiAgent
* `llama` - Llama
* `azure` - Azure
* `docling` - Docling
* `whisper_groq` - WhisperGroq
* `whisper_openai` - WhisperOpenAI
* `whisper_offline` - WhisperOffline
* `localai` - LocalAI
* `anthropic` - Anthropic
* `bronci` - Bronci
* `alibaba` - Alibaba Qwen
* `rap` - Taiwan AI RAP
* `vertex` - Vertex AI
* `cohere` - Cohere
        "order"?: integer // 非必填
        "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).
  }
]
```

**回應範例值**

```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": "掃描頁另加 OCR 19.8 credits／頁"
        },
        {
          "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": "依頁面內容量計費，顯示的是近 30 天平均"
        },
        {
          "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": "參考價；實際依 token 與 OCR 頁數計"
        }
      ]
    },
    {
      "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/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.
