> 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 // 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="#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 // 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
      "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 // 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
  "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 // 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
      "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 following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/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 `build a script that syncs our docs to a CMS` 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.