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

# ナレッジベース（旧版）

### AI アシスタントのナレッジベースファイル一覧を取得 <a href="#ai" id="ai"></a>

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

#### パラメータ

| パラメータ名               | 必須 | 型       | 説明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `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/?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/?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/?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/?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
      "status": 
      {
      }
      "parser": 
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "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
      "previewUrl": string // プレゼンテーション（pptx/ppt）の場合は、プレビュー可能な派生 PDF ファイルの URL（フロントエンドの PDF ビューアーで表示）を返します。それ以外は None です。

`file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、各
ストレージプロバイダーの presign/host ルールを含めて形式の一貫性を確保します。get_absolute_url() は誤った URL 形式を生成するため、使用しないでください。
      "createdAt": string (timestamp)
    }
  ]
}
```

**レスポンス値の例**

```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": {},
        "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,
      "previewUrl": "レスポンス文字列",
      "createdAt": "レスポンス文字列"
    }
  ]
}
```

***

### AI アシスタントのナレッジベース FAQ 一覧を取得 <a href="#ai-faq" id="ai-faq"></a>

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

#### パラメータ

| パラメータ名               | 必須 | 型       | 説明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `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/?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/?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/?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/?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 // 回答内の画像や動画などのメディアファイルの URL (任意)
      "hitsCount": integer
      "embeddingTokensCount": integer // この FAQ の作成時に使用した embedding token 数
      "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="#ai" id="ai"></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 // フロントエンドで画像をプレビューできるように、ファイル URL と種類を含む完全な ChatbotFile 情報を返します
      "knowledgeBaseFile": object // get_chatbot_file と同じで、後方互換性を提供します
      "pageNumber": integer // Backward-compatible alias of ``page_start``.
      "pageStart": integer
      "pageEnd": integer
      "citationTitle": string // inline citation のホバーカードに表示する出典タイトル
      "citationDescription": string // inline citation のホバーカードに表示する出典の説明
      "citationQuote": string // inline citation のホバーカードに表示する引用テキスト
      "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 の key と value を独自に定義できます (任意)
      "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
    }
  ]
}
```

**レスポンス値の例**

```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="#ai" id="ai"></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 // フロントエンドで画像をプレビューできるように、ファイル URL と種類を含む完全な ChatbotFile 情報を返します
  "knowledgeBaseFile": object // get_chatbot_file と同じで、後方互換性を提供します
  "pageNumber": integer // Backward-compatible alias of ``page_start``.
  "pageStart": integer
  "pageEnd": integer
  "citationTitle": string // inline citation のホバーカードに表示する出典タイトル
  "citationDescription": string // inline citation のホバーカードに表示する出典の説明
  "citationQuote": string // inline citation のホバーカードに表示する引用テキスト
  "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 の key と value を自由に定義できます（任意）
  "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
}
```

**レスポンス値の例**

```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="#undefined" id="undefined"></a>

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

#### パラメーター

| パラメーター名              | 必須 | 型       | 説明                                                                      |
| -------------------- | -- | ------- | ----------------------------------------------------------------------- |
| `id`                 | ✅  | string  |                                                                         |
| `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/?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/?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/?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": null
    }

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/?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 // フロントエンドでの画像プレビュー用に、ファイル URL と型を含む ChatbotFile の完全な情報を返します
      "knowledgeBaseFile": object // get_chatbot_file と同じで、後方互換性のために提供されます
      "pageNumber": integer // Backward-compatible alias of ``page_start``.
      "pageStart": integer
      "pageEnd": integer
      "citationTitle": string // inline citation hover card に表示する出典タイトルです
      "citationDescription": string // inline citation hover card に表示する出典の説明です
      "citationQuote": string // 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 の key と value を自由に定義できます（任意）
      "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
    }
  ]
}
```

**レスポンス値の例**

```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="#undefined" id="undefined"></a>

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

#### パラメーター

| パラメーター名           | 必須 | 型      | 説明                                                                                                                                     |
| ----------------- | -- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBaseId` | ❌  | string | Knowledge base ID. When provided and the knowledge base does not support multimodal embeddings, image file types will be filtered out. |

#### コード例

{% 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
        "provider": 
        {
        }
        "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
        },
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".doc",
      "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": ".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": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".pptx",
      "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": ".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
        },
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "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": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".mp3",
      "parsers": [
        {
          "id": "4c47e305-2eb7-4438-8d3c-d91eb0b06cc0",
          "name": "Azure Speech",
          "provider": "azure",
          "order": 1,
          "isDefault": true
        },
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".wav",
      "parsers": [
        {
          "id": "4c47e305-2eb7-4438-8d3c-d91eb0b06cc0",
          "name": "Azure Speech",
          "provider": "azure",
          "order": 1,
          "isDefault": true
        },
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    },
    {
      "fileType": ".mp4",
      "parsers": [
        {
          "id": "22fdcbb5-f075-4aad-bb81-048289ca4b25",
          "name": "MaiAgent Parser (Online)",
          "provider": "llama",
          "order": 2,
          "isDefault": false
        }
      ]
    }
  ]
]
```

***


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/api/ja/api-reference/zhi-shi-ku-jiu-ban.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.