# 知識庫（新版）

### 建立知識庫 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/`

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| embeddingModel          | string (uuid)   | 是  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 是  |                                                                                                                                                                                      |
| name                    | string          | 是  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default.                      |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  |                                                                                                                                                                                      |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/", 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/knowledge-bases/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

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/knowledge-bases/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 建立知識庫 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/`

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| embeddingModel          | string (uuid)   | 是  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 是  |                                                                                                                                                                                      |
| name                    | string          | 是  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default.                      |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  |                                                                                                                                                                                      |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. If not provided, uses system default. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/", 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/knowledge-bases/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

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/knowledge-bases/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 列出所有知識庫 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/`

#### 參數

| 參數名稱             | 必填 | 類型      | 說明                                             |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `embeddingModel` | ❌  | string  |                                                |
| `page`           | ❌  | integer | A page number within the paginated result set. |
| `pageSize`       | ❌  | integer | Number of results to return per page.          |
| `query`          | ❌  | string  |                                                |
| `rerankerModel`  | ❌  | string  |                                                |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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)
      "createdBy"?: string (uuid) // 非必填
      "organization"?: string (uuid) // 非必填
      "embeddingModel": string (uuid)
      "rerankerModel": string (uuid)
      "name": string
      "description"?: string // 非必填
      "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
      "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
      "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
      "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
      "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
      "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
      "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
      {
      }
      "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
      "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
      "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
      "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
      "oracleUser"?: string // Oracle database username. (非必填)
      "oraclePassword"?: string // Oracle database password. (非必填)
      "labels": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "chatbots"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "groups"?: [ // 知識庫可存取的群組列表 (非必填)
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
      "vectorStorageSize": integer
      "chunksCount": integer
      "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "numberOfRetrievedChunks": 456,
      "sentenceWindowSize": 456,
      "enableHyde": false,
      "similarityCutoff": 456,
      "enableRerank": false,
      "enableRrf": false,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "回應字串",
      "vectorDatabaseApiKey": "回應字串",
      "opensearchUsername": "回應字串",
      "opensearchPassword": "回應字串",
      "oracleUser": "回應字串",
      "oraclePassword": "回應字串",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "filesCount": 456,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "isMultimodal": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 列出所有知識庫 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/`

#### 參數

| 參數名稱             | 必填 | 類型      | 說明                                             |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `embeddingModel` | ❌  | string  |                                                |
| `page`           | ❌  | integer | A page number within the paginated result set. |
| `pageSize`       | ❌  | integer | Number of results to return per page.          |
| `query`          | ❌  | string  |                                                |
| `rerankerModel`  | ❌  | string  |                                                |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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)
      "createdBy"?: string (uuid) // 非必填
      "organization"?: string (uuid) // 非必填
      "embeddingModel": string (uuid)
      "rerankerModel": string (uuid)
      "name": string
      "description"?: string // 非必填
      "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
      "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
      "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
      "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
      "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
      "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
      "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
      {
      }
      "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
      "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
      "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
      "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
      "oracleUser"?: string // Oracle database username. (非必填)
      "oraclePassword"?: string // Oracle database password. (非必填)
      "labels": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "chatbots"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "groups"?: [ // 知識庫可存取的群組列表 (非必填)
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
      "vectorStorageSize": integer
      "chunksCount": integer
      "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "numberOfRetrievedChunks": 456,
      "sentenceWindowSize": 456,
      "enableHyde": false,
      "similarityCutoff": 456,
      "enableRerank": false,
      "enableRrf": false,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "回應字串",
      "vectorDatabaseApiKey": "回應字串",
      "opensearchUsername": "回應字串",
      "opensearchPassword": "回應字串",
      "oracleUser": "回應字串",
      "oraclePassword": "回應字串",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "filesCount": 456,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "isMultimodal": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 取得特定知識庫詳情 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/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/knowledge-bases/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/knowledge-bases/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/knowledge-bases/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)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 取得特定知識庫詳情 <a href="#undefined" id="undefined"></a>

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

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/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/knowledge-bases/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/knowledge-bases/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/knowledge-bases/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)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 更新知識庫 <a href="#undefined" id="undefined"></a>

PUT `/api/knowledge-bases/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| createdBy               | string (uuid)   | 否  |                                                                                                                                                                                      |
| organization            | string (uuid)   | 否  |                                                                                                                                                                                      |
| embeddingModel          | string (uuid)   | 是  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 是  |                                                                                                                                                                                      |
| name                    | string          | 是  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license.                                                            |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  | 知識庫可存取的群組列表                                                                                                                                                                          |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "createdBy": "550e8400-e29b-41d4-a716-446655440000",
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 更新知識庫 <a href="#undefined" id="undefined"></a>

PUT `/api/v1/knowledge-bases/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| createdBy               | string (uuid)   | 否  |                                                                                                                                                                                      |
| organization            | string (uuid)   | 否  |                                                                                                                                                                                      |
| embeddingModel          | string (uuid)   | 是  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 是  |                                                                                                                                                                                      |
| name                    | string          | 是  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license.                                                            |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  | 知識庫可存取的群組列表                                                                                                                                                                          |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "createdBy": "550e8400-e29b-41d4-a716-446655440000",
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 部分更新知識庫 <a href="#undefined" id="undefined"></a>

PATCH `/api/knowledge-bases/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| createdBy               | string (uuid)   | 否  |                                                                                                                                                                                      |
| organization            | string (uuid)   | 否  |                                                                                                                                                                                      |
| embeddingModel          | string (uuid)   | 否  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 否  |                                                                                                                                                                                      |
| name                    | string          | 否  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license.                                                            |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  | 知識庫可存取的群組列表                                                                                                                                                                          |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel"?: string (uuid) // 非必填
  "rerankerModel"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "createdBy": "550e8400-e29b-41d4-a716-446655440000",
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 部分更新知識庫 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/knowledge-bases/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                      | 類型              | 必填 | 說明                                                                                                                                                                                   |
| ----------------------- | --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| createdBy               | string (uuid)   | 否  |                                                                                                                                                                                      |
| organization            | string (uuid)   | 否  |                                                                                                                                                                                      |
| embeddingModel          | string (uuid)   | 否  |                                                                                                                                                                                      |
| rerankerModel           | string (uuid)   | 否  |                                                                                                                                                                                      |
| name                    | string          | 否  |                                                                                                                                                                                      |
| description             | string          | 否  |                                                                                                                                                                                      |
| numberOfRetrievedChunks | integer         | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                                                                                                              |
| sentenceWindowSize      | integer         | 否  | RAG 擴增句子視窗大小，預設為 2，最小值為 0                                                                                                                                                            |
| enableHyde              | boolean         | 否  | 啟用 HyDE，預設為 False                                                                                                                                                                    |
| similarityCutoff        | number (double) | 否  | 相似度門檻，預設為 0.0，範圍為 0.0-1.0                                                                                                                                                            |
| enableRerank            | boolean         | 否  | 是否啟用重新排序，預設為 True                                                                                                                                                                    |
| enableRrf               | boolean         | 否  | Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license.                                                            |
| vectorDatabaseType      | object          | 否  | Type of vector database: elasticsearch or opensearch. `elasticsearch`: Elasticsearch ; `opensearch`: OpenSearch ; `oracle`: Oracle AI Database 26ai;                                 |
| vectorDatabaseUrl       | string          | 否  | Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "<https://host:9200>"). For Oracle: DSN format (e.g., "host:1521/service\_name"). |
| vectorDatabaseApiKey    | string          | 否  | API Key for Elasticsearch. Not used for OpenSearch.                                                                                                                                  |
| opensearchUsername      | string          | 否  | Username for OpenSearch Basic Auth.                                                                                                                                                  |
| opensearchPassword      | string          | 否  | Password for OpenSearch Basic Auth.                                                                                                                                                  |
| oracleUser              | string          | 否  | Oracle database username.                                                                                                                                                            |
| oraclePassword          | string          | 否  | Oracle database password.                                                                                                                                                            |
| chatbots                | array\[IdName]  | 否  |                                                                                                                                                                                      |
| groups                  | array\[IdName]  | 否  | 知識庫可存取的群組列表                                                                                                                                                                          |
| isMultimodal            | boolean         | 否  | Whether this knowledge base supports multimodal embeddings (text + images).                                                                                                          |

**請求結構範例**

```typescript
{
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel"?: string (uuid) // 非必填
  "rerankerModel"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
}
```

**請求範例值**

```json
{
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "enableRrf": true,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "範例字串",
  "vectorDatabaseApiKey": "範例字串",
  "opensearchUsername": "範例字串",
  "opensearchPassword": "範例字串",
  "oracleUser": "範例字串",
  "oraclePassword": "範例字串",
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "isMultimodal": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  }'

# 請確認在執行前替換 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 = {
    "createdBy": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "enableRrf": true,
    "vectorDatabaseType": {},
    "vectorDatabaseUrl": "範例字串",
    "vectorDatabaseApiKey": "範例字串",
    "opensearchUsername": "範例字串",
    "opensearchPassword": "範例字串",
    "oracleUser": "範例字串",
    "oraclePassword": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "isMultimodal": true
  };

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "範例名稱",
      "description": "範例字串",
      "numberOfRetrievedChunks": 123,
      "sentenceWindowSize": 123,
      "enableHyde": true,
      "similarityCutoff": 123,
      "enableRerank": true,
      "enableRrf": true,
      "vectorDatabaseType": {},
      "vectorDatabaseUrl": "範例字串",
      "vectorDatabaseApiKey": "範例字串",
      "opensearchUsername": "範例字串",
      "opensearchPassword": "範例字串",
      "oracleUser": "範例字串",
      "oraclePassword": "範例字串",
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "isMultimodal": true
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "createdBy": "550e8400-e29b-41d4-a716-446655440000",
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "name": "範例名稱",
            "description": "範例字串",
            "numberOfRetrievedChunks": 123,
            "sentenceWindowSize": 123,
            "enableHyde": true,
            "similarityCutoff": 123,
            "enableRerank": true,
            "enableRrf": true,
            "vectorDatabaseType": {},
            "vectorDatabaseUrl": "範例字串",
            "vectorDatabaseApiKey": "範例字串",
            "opensearchUsername": "範例字串",
            "opensearchPassword": "範例字串",
            "oracleUser": "範例字串",
            "oraclePassword": "範例字串",
            "chatbots": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "isMultimodal": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 刪除知識庫 <a href="#undefined" id="undefined"></a>

DELETE `/api/knowledge-bases/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(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->delete("https://api.maiagent.ai/api/knowledge-bases/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 %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除知識庫 <a href="#undefined" id="undefined"></a>

DELETE `/api/v1/knowledge-bases/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 檢查 RRF 可用性 <a href="#rrf" id="rrf"></a>

GET `/api/knowledge-bases/{id}/check-rrf-availability/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/" \
  -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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", [
        '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)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 檢查 RRF 可用性 <a href="#rrf" id="rrf"></a>

GET `/api/v1/knowledge-bases/{id}/check-rrf-availability/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/check-rrf-availability/", [
        '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)
  "createdBy"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
  "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
  {
  }
  "vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
  "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
  "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
  "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
  "oracleUser"?: string // Oracle database username. (非必填)
  "oraclePassword"?: string // Oracle database password. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
  "vectorStorageSize": integer
  "chunksCount": integer
  "isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "enableRrf": false,
  "vectorDatabaseType": {},
  "vectorDatabaseUrl": "回應字串",
  "vectorDatabaseApiKey": "回應字串",
  "opensearchUsername": "回應字串",
  "opensearchPassword": "回應字串",
  "oracleUser": "回應字串",
  "oraclePassword": "回應字串",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "filesCount": 456,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "isMultimodal": false,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 匯出標籤 Excel <a href="#excel" id="excel"></a>

GET `/api/knowledge-bases/{id}/export-labels-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/" \
  -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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", [
        '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 | Excel file download |

***

### 匯出標籤 Excel <a href="#excel" id="excel"></a>

GET `/api/v1/knowledge-bases/{id}/export-labels-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-labels-excel/", [
        '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 | Excel file download |

***

### 匯入標籤 Excel <a href="#excel" id="excel"></a>

POST `/api/knowledge-bases/{id}/import-labels-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "excelFile=@example_file.txt"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('excelFile', /* 實際檔案物件 */, 'example_file.txt');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", formData, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}

response = requests.post(url, files=files, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'excelFile',
                'contents' => fopen('example_file.txt', 'r'),
                'filename' => 'example_file.txt'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "success"?: boolean // 非必填
  "updated_count"?: integer // 非必填
  "total_rows"?: integer // 非必填
  "errors"?: [ // 非必填
    {
      "row"?: integer // 非必填
      "file_id"?: string // 非必填
      "error"?: string // 非必填
    }
  ]
}
```

**回應範例值**

```json
{
  "success": false,
  "updated_count": 456,
  "total_rows": 456,
  "errors": [
    {
      "row": 456,
      "file_id": "回應字串",
      "error": "回應字串"
    }
  ]
}
```

***

### 匯入標籤 Excel <a href="#excel" id="excel"></a>

POST `/api/v1/knowledge-bases/{id}/import-labels-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "excelFile=@example_file.txt"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('excelFile', /* 實際檔案物件 */, 'example_file.txt');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}

response = requests.post(url, files=files, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-labels-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'excelFile',
                'contents' => fopen('example_file.txt', 'r'),
                'filename' => 'example_file.txt'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "success"?: boolean // 非必填
  "updated_count"?: integer // 非必填
  "total_rows"?: integer // 非必填
  "errors"?: [ // 非必填
    {
      "row"?: integer // 非必填
      "file_id"?: string // 非必填
      "error"?: string // 非必填
    }
  ]
}
```

**回應範例值**

```json
{
  "success": false,
  "updated_count": 456,
  "total_rows": 456,
  "errors": [
    {
      "row": 456,
      "file_id": "回應字串",
      "error": "回應字串"
    }
  ]
}
```

***

### 匯出元資料 Excel <a href="#excel" id="excel"></a>

GET `/api/knowledge-bases/{id}/export-metadata-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/" \
  -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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", [
        '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 | Excel 檔案下載 |

***

### 匯出元資料 Excel <a href="#excel" id="excel"></a>

GET `/api/v1/knowledge-bases/{id}/export-metadata-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/export-metadata-excel/", [
        '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 | Excel 檔案下載 |

***

### 匯入元資料 Excel <a href="#excel" id="excel"></a>

POST `/api/knowledge-bases/{id}/import-metadata-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "excelFile=@example_file.txt"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('excelFile', /* 實際檔案物件 */, 'example_file.txt');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", formData, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}

response = requests.post(url, files=files, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'excelFile',
                'contents' => fopen('example_file.txt', 'r'),
                'filename' => 'example_file.txt'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "success"?: boolean // 非必填
  "updated_count"?: integer // 非必填
  "total_rows"?: integer // 非必填
  "errors"?: [ // 非必填
    {
      "row"?: integer // 非必填
      "file_id"?: string // 非必填
      "error"?: string // 非必填
    }
  ]
}
```

**回應範例值**

```json
{
  "success": false,
  "updated_count": 456,
  "total_rows": 456,
  "errors": [
    {
      "row": 456,
      "file_id": "回應字串",
      "error": "回應字串"
    }
  ]
}
```

***

### 匯入元資料 Excel <a href="#excel" id="excel"></a>

POST `/api/v1/knowledge-bases/{id}/import-metadata-excel/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "excelFile=@example_file.txt"

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

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('excelFile', /* 實際檔案物件 */, 'example_file.txt');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'excelFile': ('example_file.txt', open('example_file.txt', 'rb'), 'text/plain')
}

response = requests.post(url, files=files, 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/import-metadata-excel/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'excelFile',
                'contents' => fopen('example_file.txt', 'r'),
                'filename' => 'example_file.txt'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "success"?: boolean // 非必填
  "updated_count"?: integer // 非必填
  "total_rows"?: integer // 非必填
  "errors"?: [ // 非必填
    {
      "row"?: integer // 非必填
      "file_id"?: string // 非必填
      "error"?: string // 非必填
    }
  ]
}
```

**回應範例值**

```json
{
  "success": false,
  "updated_count": 456,
  "total_rows": 456,
  "errors": [
    {
      "row": 456,
      "file_id": "回應字串",
      "error": "回應字串"
    }
  ]
}
```

***

### 建立新標籤 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/labels/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 建立新標籤 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 列出知識庫中的標籤 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/labels/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                             |
| ----------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                |
| `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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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)
      "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",
      "name": "回應字串"
    }
  ]
}
```

***

### 列出知識庫中的標籤 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                             |
| ----------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                |
| `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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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)
      "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",
      "name": "回應字串"
    }
  ]
}
```

***

### 取得特定標籤詳情 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 取得特定標籤詳情 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 更新標籤 <a href="#undefined" id="undefined"></a>

PUT `/api/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 更新標籤 <a href="#undefined" id="undefined"></a>

PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 部分更新標籤 <a href="#undefined" id="undefined"></a>

PATCH `/api/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 否  |    |

**請求結構範例**

```typescript
{
  "name"?: string // 非必填
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 部分更新標籤 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 否  |    |

**請求結構範例**

```typescript
{
  "name"?: string // 非必填
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 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 = {
    "name": "範例名稱"
  };

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name"?: string // 非必填
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串"
}
```

***

### 刪除標籤 <a href="#undefined" id="undefined"></a>

DELETE `/api/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除標籤 <a href="#undefined" id="undefined"></a>

DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/labels/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 建立元資料欄位 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/metadata-keys/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明                |
| ---------------- | ------- | -- | ----------------- |
| keyName          | string  | 是  | Metadata 的 key 名稱 |
| description      | string  | 否  | 說明此欄位的用途          |
| isRequired       | boolean | 否  | 是否為必填欄位           |
| defaultValue     | string  | 否  | 新檔案的預設值           |
| enabledForSearch | boolean | 否  | 是否在檢索時使用此欄位       |

**請求結構範例**

```typescript
{
  "keyName": string // Metadata 的 key 名稱
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
}
```

**請求範例值**

```json
{
  "keyName": "範例字串",
  "description": "範例字串",
  "isRequired": true,
  "defaultValue": "範例字串",
  "enabledForSearch": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  }'

# 請確認在執行前替換 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 = {
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "keyName": "範例字串",
      "description": "範例字串",
      "isRequired": true,
      "defaultValue": "範例字串",
      "enabledForSearch": true
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "keyName": "範例字串",
            "description": "範例字串",
            "isRequired": true,
            "defaultValue": "範例字串",
            "enabledForSearch": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 建立元資料欄位 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明                |
| ---------------- | ------- | -- | ----------------- |
| keyName          | string  | 是  | Metadata 的 key 名稱 |
| description      | string  | 否  | 說明此欄位的用途          |
| isRequired       | boolean | 否  | 是否為必填欄位           |
| defaultValue     | string  | 否  | 新檔案的預設值           |
| enabledForSearch | boolean | 否  | 是否在檢索時使用此欄位       |

**請求結構範例**

```typescript
{
  "keyName": string // Metadata 的 key 名稱
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
}
```

**請求範例值**

```json
{
  "keyName": "範例字串",
  "description": "範例字串",
  "isRequired": true,
  "defaultValue": "範例字串",
  "enabledForSearch": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  }'

# 請確認在執行前替換 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 = {
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "keyName": "範例字串",
      "description": "範例字串",
      "isRequired": true,
      "defaultValue": "範例字串",
      "enabledForSearch": true
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "keyName": "範例字串",
            "description": "範例字串",
            "isRequired": true,
            "defaultValue": "範例字串",
            "enabledForSearch": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 列出元資料欄位 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/metadata-keys/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                             |
| ----------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                |
| `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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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)
      "knowledgeBase": 
      {
        "id": string (uuid)
        "name": string
      }
      "keyName": string // Metadata 的 key 名稱
      "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
      "description"?: string // 說明此欄位的用途 (非必填)
      "isRequired"?: boolean // 是否為必填欄位 (非必填)
      "defaultValue"?: string // 新檔案的預設值 (非必填)
      "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "keyName": "回應字串",
      "keyType": "回應字串",
      "description": "回應字串",
      "isRequired": false,
      "defaultValue": "回應字串",
      "enabledForSearch": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 列出元資料欄位 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                             |
| ----------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                |
| `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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/?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)
      "knowledgeBase": 
      {
        "id": string (uuid)
        "name": string
      }
      "keyName": string // Metadata 的 key 名稱
      "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
      "description"?: string // 說明此欄位的用途 (非必填)
      "isRequired"?: boolean // 是否為必填欄位 (非必填)
      "defaultValue"?: string // 新檔案的預設值 (非必填)
      "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": 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",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "keyName": "回應字串",
      "keyType": "回應字串",
      "description": "回應字串",
      "isRequired": false,
      "defaultValue": "回應字串",
      "enabledForSearch": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 取得特定元資料欄位 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 取得特定元資料欄位 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 更新元資料欄位 <a href="#undefined" id="undefined"></a>

PUT `/api/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明                |
| ---------------- | ------- | -- | ----------------- |
| keyName          | string  | 是  | Metadata 的 key 名稱 |
| description      | string  | 否  | 說明此欄位的用途          |
| isRequired       | boolean | 否  | 是否為必填欄位           |
| defaultValue     | string  | 否  | 新檔案的預設值           |
| enabledForSearch | boolean | 否  | 是否在檢索時使用此欄位       |

**請求結構範例**

```typescript
{
  "keyName": string // Metadata 的 key 名稱
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
}
```

**請求範例值**

```json
{
  "keyName": "範例字串",
  "description": "範例字串",
  "isRequired": true,
  "defaultValue": "範例字串",
  "enabledForSearch": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  }'

# 請確認在執行前替換 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 = {
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "keyName": "範例字串",
      "description": "範例字串",
      "isRequired": true,
      "defaultValue": "範例字串",
      "enabledForSearch": true
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "keyName": "範例字串",
            "description": "範例字串",
            "isRequired": true,
            "defaultValue": "範例字串",
            "enabledForSearch": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 更新元資料欄位 <a href="#undefined" id="undefined"></a>

PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明                |
| ---------------- | ------- | -- | ----------------- |
| keyName          | string  | 是  | Metadata 的 key 名稱 |
| description      | string  | 否  | 說明此欄位的用途          |
| isRequired       | boolean | 否  | 是否為必填欄位           |
| defaultValue     | string  | 否  | 新檔案的預設值           |
| enabledForSearch | boolean | 否  | 是否在檢索時使用此欄位       |

**請求結構範例**

```typescript
{
  "keyName": string // Metadata 的 key 名稱
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
}
```

**請求範例值**

```json
{
  "keyName": "範例字串",
  "description": "範例字串",
  "isRequired": true,
  "defaultValue": "範例字串",
  "enabledForSearch": true
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  }'

# 請確認在執行前替換 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 = {
    "keyName": "範例字串",
    "description": "範例字串",
    "isRequired": true,
    "defaultValue": "範例字串",
    "enabledForSearch": true
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "keyName": "範例字串",
      "description": "範例字串",
      "isRequired": true,
      "defaultValue": "範例字串",
      "enabledForSearch": true
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/metadata-keys/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "keyName": "範例字串",
            "description": "範例字串",
            "isRequired": true,
            "defaultValue": "範例字串",
            "enabledForSearch": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "knowledgeBase": 
  {
    "id": string (uuid)
    "name": string
  }
  "keyName": string // Metadata 的 key 名稱
  "keyType": string // 根據欄位名稱自動判斷（預設欄位或自定欄位）
  "description"?: string // 說明此欄位的用途 (非必填)
  "isRequired"?: boolean // 是否為必填欄位 (非必填)
  "defaultValue"?: string // 新檔案的預設值 (非必填)
  "enabledForSearch"?: boolean // 是否在檢索時使用此欄位 (非必填)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "keyName": "回應字串",
  "keyType": "回應字串",
  "description": "回應字串",
  "isRequired": false,
  "defaultValue": "回應字串",
  "enabledForSearch": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 上傳檔案到知識庫 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/files/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 請求內容

**請求參數**

| 欄位    | 類型                              | 必填 | 說明                       |
| ----- | ------------------------------- | -- | ------------------------ |
| files | array\[KnowledgeBaseFileCreate] | 是  | 支援多檔案批次上傳功能，上限為單次 50 個檔案 |

**請求結構範例**

```typescript
{
  "files": [ // 支援多檔案批次上傳功能，上限為單次 50 個檔案
    {
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "parser"?: string (uuid) // 非必填
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
    }
  ]
}
```

**請求範例值**

```json
{
  "files": [
    {
      "filename": "my-file.pdf",
      "file": "string",
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "labels": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "my-label"
        }
      ],
      "rawUserDefineMetadata": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "filename": "you-can-upload-multiple-files.pdf",
      "file": "string",
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "my-file.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "labels": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "my-label"
          }
        ],
        "rawUserDefineMetadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "filename": "you-can-upload-multiple-files.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  }'

# 請確認在執行前替換 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 = {
    "files": [
      {
        "filename": "my-file.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "labels": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "my-label"
          }
        ],
        "rawUserDefineMetadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "filename": "you-can-upload-multiple-files.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "files": [
        {
          "filename": "my-file.pdf",
          "file": "string",
          "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "labels": [
            {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "name": "my-label"
            }
          ],
          "rawUserDefineMetadata": {
            "key1": "value1",
            "key2": "value2"
          }
        },
        {
          "filename": "you-can-upload-multiple-files.pdf",
          "file": "string",
          "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      ]
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "files": [
                {
                    "filename": "my-file.pdf",
                    "file": "string",
                    "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "labels": [
                        {
                            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                            "name": "my-label"
                        }
                    ],
                    "rawUserDefineMetadata": {
                        "key1": "value1",
                        "key2": "value2"
                    }
                },
                {
                    "filename": "you-can-upload-multiple-files.pdf",
                    "file": "string",
                    "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 上傳檔案到知識庫 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 請求內容

**請求參數**

| 欄位    | 類型                              | 必填 | 說明                       |
| ----- | ------------------------------- | -- | ------------------------ |
| files | array\[KnowledgeBaseFileCreate] | 是  | 支援多檔案批次上傳功能，上限為單次 50 個檔案 |

**請求結構範例**

```typescript
{
  "files": [ // 支援多檔案批次上傳功能，上限為單次 50 個檔案
    {
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "parser"?: string (uuid) // 非必填
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
    }
  ]
}
```

**請求範例值**

```json
{
  "files": [
    {
      "filename": "my-file.pdf",
      "file": "string",
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "labels": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "my-label"
        }
      ],
      "rawUserDefineMetadata": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "filename": "you-can-upload-multiple-files.pdf",
      "file": "string",
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "my-file.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "labels": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "my-label"
          }
        ],
        "rawUserDefineMetadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "filename": "you-can-upload-multiple-files.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  }'

# 請確認在執行前替換 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 = {
    "files": [
      {
        "filename": "my-file.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "labels": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "my-label"
          }
        ],
        "rawUserDefineMetadata": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "filename": "you-can-upload-multiple-files.pdf",
        "file": "string",
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "files": [
        {
          "filename": "my-file.pdf",
          "file": "string",
          "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "labels": [
            {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "name": "my-label"
            }
          ],
          "rawUserDefineMetadata": {
            "key1": "value1",
            "key2": "value2"
          }
        },
        {
          "filename": "you-can-upload-multiple-files.pdf",
          "file": "string",
          "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      ]
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "files": [
                {
                    "filename": "my-file.pdf",
                    "file": "string",
                    "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "labels": [
                        {
                            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                            "name": "my-label"
                        }
                    ],
                    "rawUserDefineMetadata": {
                        "key1": "value1",
                        "key2": "value2"
                    }
                },
                {
                    "filename": "you-can-upload-multiple-files.pdf",
                    "file": "string",
                    "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 批量刪除檔案 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/files/batch-delete/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位  | 類型             | 必填 | 說明 |
| --- | -------------- | -- | -- |
| ids | array\[string] | 是  |    |

**請求結構範例**

```typescript
{
  "ids": [
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 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 = {
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "ids": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "ids": [
                "550e8400-e29b-41d4-a716-446655440000"
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 批量刪除檔案 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/batch-delete/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位  | 類型             | 必填 | 說明 |
| --- | -------------- | -- | -- |
| ids | array\[string] | 是  |    |

**請求結構範例**

```typescript
{
  "ids": [
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 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 = {
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "ids": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "ids": [
                "550e8400-e29b-41d4-a716-446655440000"
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 批量重新解析檔案 <a href="#undefined" id="undefined"></a>

PATCH `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型             | 必填 | 說明     |
| --------------------- | -------------- | -- | ------ |
| filename              | string         | 否  | 檔案名稱   |
| file                  | string (uri)   | 否  | 要上傳的檔案 |
| parser                | string (uuid)  | 否  |        |
| labels                | array\[IdName] | 否  |        |
| rawUserDefineMetadata | object         | 否  |        |

**請求結構範例**

```typescript
{
  "filename"?: string // 檔案名稱 (非必填)
  "file"?: string (uri) // 要上傳的檔案 (非必填)
  "parser"?: string (uuid) // 非必填
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
}
```

**請求範例值**

```json
{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# 請確認在執行前替換 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 = {
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  };

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "filename": "document.pdf",
      "file": "https://example.com/file.jpg",
      "parser": "550e8400-e29b-41d4-a716-446655440000",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "filename": "document.pdf",
            "file": "https://example.com/file.jpg",
            "parser": "550e8400-e29b-41d4-a716-446655440000",
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 批量重新解析檔案 <a href="#undefined" id="undefined"></a>

PATCH `/api/knowledge-bases/{knowledgeBasePk}/files/batch-reparse/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

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

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

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

// 請求內容 (payload)
const data = [];

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

```python
import requests

url = "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = []

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => []
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

#### 回應內容

**狀態碼: 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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 批量重新解析檔案 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型             | 必填 | 說明     |
| --------------------- | -------------- | -- | ------ |
| filename              | string         | 否  | 檔案名稱   |
| file                  | string (uri)   | 否  | 要上傳的檔案 |
| parser                | string (uuid)  | 否  |        |
| labels                | array\[IdName] | 否  |        |
| rawUserDefineMetadata | object         | 否  |        |

**請求結構範例**

```typescript
{
  "filename"?: string // 檔案名稱 (非必填)
  "file"?: string (uri) // 要上傳的檔案 (非必填)
  "parser"?: string (uuid) // 非必填
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
}
```

**請求範例值**

```json
{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# 請確認在執行前替換 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 = {
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  };

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "filename": "document.pdf",
      "file": "https://example.com/file.jpg",
      "parser": "550e8400-e29b-41d4-a716-446655440000",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "filename": "document.pdf",
            "file": "https://example.com/file.jpg",
            "parser": "550e8400-e29b-41d4-a716-446655440000",
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 批量重新解析檔案 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/files/batch-reparse/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

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

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

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

// 請求內容 (payload)
const data = [];

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

```python
import requests

url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = []

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => []
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

#### 回應內容

**狀態碼: 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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 列出知識庫中的檔案 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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

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

axios.get("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

```python
import requests

url = "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

#### 回應內容

**狀態碼: 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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 列出知識庫中的檔案 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                                                                                                                                                                                     |
| ----------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                                                                                                                                                                                        |
| `fileType`        | ❌  | string  | 檔案類型過濾，例如：pdf、docx、txt、xlsx 等                                                                                                                                                                                          |
| `knowledgeBase`   | ❌  | string  | 知識庫 ID                                                                                                                                                                                                                 |
| `page`            | ❌  | integer | A page number within the paginated result set.                                                                                                                                                                         |
| `pageSize`        | ❌  | integer | Number of results to return per page.                                                                                                                                                                                  |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：檔案 ID、檔案名稱、標籤名稱、Metadata value                                                                                                                                                                  |
| `status`          | ❌  | string  | 檔案狀態過濾，可選值：initial（初始化）、processing（處理中）、done（完成）、deleting（刪除中）、deleted（已刪除）、failed（失敗） \`initial\`: Initial ; \`processing\`: Processing ; \`done\`: Done ; \`deleting\`: Deleting ; \`deleted\`: Deleted ; \`faile... |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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

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

axios.get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

```python
import requests

url = "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=delete_failed", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

#### 回應內容

**狀態碼: 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": 
        {
        }
        "order"?: integer // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "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
      "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": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 取得特定檔案詳情 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 取得特定檔案詳情 <a href="#undefined" id="undefined"></a>

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

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 取得檔案最新失敗原因 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/latest-failed-reason/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/" \
  -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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "errorMessage": string
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "errorMessage": "回應字串",
  "createdAt": "回應字串"
}
```

***

### 取得檔案最新失敗原因 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/latest-failed-reason/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/latest-failed-reason/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "errorMessage": string
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "errorMessage": "回應字串",
  "createdAt": "回應字串"
}
```

***

### 取得檔案轉錄內容 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/transcription/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/" \
  -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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 取得檔案轉錄內容 <a href="#undefined" id="undefined"></a>

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

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/transcription/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 更新檔案資訊 <a href="#undefined" id="undefined"></a>

PUT `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型             | 必填 | 說明     |
| --------------------- | -------------- | -- | ------ |
| filename              | string         | 是  | 檔案名稱   |
| file                  | string (uri)   | 是  | 要上傳的檔案 |
| parser                | string (uuid)  | 否  |        |
| labels                | array\[IdName] | 否  |        |
| rawUserDefineMetadata | object         | 否  |        |

**請求結構範例**

```typescript
{
  "filename": string // 檔案名稱
  "file": string (uri) // 要上傳的檔案
  "parser"?: string (uuid) // 非必填
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
}
```

**請求範例值**

```json
{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# 請確認在執行前替換 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 = {
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "filename": "document.pdf",
      "file": "https://example.com/file.jpg",
      "parser": "550e8400-e29b-41d4-a716-446655440000",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "filename": "document.pdf",
            "file": "https://example.com/file.jpg",
            "parser": "550e8400-e29b-41d4-a716-446655440000",
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 更新檔案資訊 <a href="#undefined" id="undefined"></a>

PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型             | 必填 | 說明     |
| --------------------- | -------------- | -- | ------ |
| filename              | string         | 是  | 檔案名稱   |
| file                  | string (uri)   | 是  | 要上傳的檔案 |
| parser                | string (uuid)  | 否  |        |
| labels                | array\[IdName] | 否  |        |
| rawUserDefineMetadata | object         | 否  |        |

**請求結構範例**

```typescript
{
  "filename": string // 檔案名稱
  "file": string (uri) // 要上傳的檔案
  "parser"?: string (uuid) // 非必填
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
}
```

**請求範例值**

```json
{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# 請確認在執行前替換 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 = {
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "filename": "document.pdf",
      "file": "https://example.com/file.jpg",
      "parser": "550e8400-e29b-41d4-a716-446655440000",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "filename": "document.pdf",
            "file": "https://example.com/file.jpg",
            "parser": "550e8400-e29b-41d4-a716-446655440000",
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "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": 
    {
    }
    "order"?: integer // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "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
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "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": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}
```

***

### 刪除檔案 <a href="#undefined" id="undefined"></a>

DELETE `/api/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除檔案 <a href="#undefined" id="undefined"></a>

DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 建立檔案翻譯 <a href="#undefined" id="undefined"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`

#### 參數

| 參數名稱                  | 必填 | 類型     | 說明 |
| --------------------- | -- | ------ | -- |
| `knowledgeBaseFilePk` | ✅  | string |    |
| `knowledgeBasePk`     | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位                   | 類型            | 必填 | 說明 |
| -------------------- | ------------- | -- | -- |
| sourceLanguage       | string        | 否  |    |
| targetLanguage       | string        | 是  |    |
| customPrompt         | string        | 否  |    |
| largeLanguageModelId | string (uuid) | 是  |    |

**請求結構範例**

```typescript
{
  "sourceLanguage"?: string // 非必填
  "targetLanguage": string
  "customPrompt"?: string // 非必填
  "largeLanguageModelId": string (uuid)
}
```

**請求範例值**

```json
{
  "sourceLanguage": "範例字串",
  "targetLanguage": "範例字串",
  "customPrompt": "範例字串",
  "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLanguage": "範例字串",
    "targetLanguage": "範例字串",
    "customPrompt": "範例字串",
    "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 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 = {
    "sourceLanguage": "範例字串",
    "targetLanguage": "範例字串",
    "customPrompt": "範例字串",
    "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "sourceLanguage": "範例字串",
      "targetLanguage": "範例字串",
      "customPrompt": "範例字串",
      "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
    }

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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "sourceLanguage": "範例字串",
            "targetLanguage": "範例字串",
            "customPrompt": "範例字串",
            "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "sourceLanguage"?: string // 非必填
  "targetLanguage": string
  "customPrompt"?: string // 非必填
  "largeLanguageModelId": string (uuid)
}
```

**回應範例值**

```json
{
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```

***

### 建立檔案翻譯 <a href="#undefined" id="undefined"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`

#### 參數

| 參數名稱                  | 必填 | 類型     | 說明 |
| --------------------- | -- | ------ | -- |
| `knowledgeBaseFilePk` | ✅  | string |    |
| `knowledgeBasePk`     | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位                   | 類型            | 必填 | 說明 |
| -------------------- | ------------- | -- | -- |
| sourceLanguage       | string        | 否  |    |
| targetLanguage       | string        | 是  |    |
| customPrompt         | string        | 否  |    |
| largeLanguageModelId | string (uuid) | 是  |    |

**請求結構範例**

```typescript
{
  "sourceLanguage"?: string // 非必填
  "targetLanguage": string
  "customPrompt"?: string // 非必填
  "largeLanguageModelId": string (uuid)
}
```

**請求範例值**

```json
{
  "sourceLanguage": "範例字串",
  "targetLanguage": "範例字串",
  "customPrompt": "範例字串",
  "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLanguage": "範例字串",
    "targetLanguage": "範例字串",
    "customPrompt": "範例字串",
    "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 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 = {
    "sourceLanguage": "範例字串",
    "targetLanguage": "範例字串",
    "customPrompt": "範例字串",
    "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "sourceLanguage": "範例字串",
      "targetLanguage": "範例字串",
      "customPrompt": "範例字串",
      "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
    }

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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "sourceLanguage": "範例字串",
            "targetLanguage": "範例字串",
            "customPrompt": "範例字串",
            "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "sourceLanguage"?: string // 非必填
  "targetLanguage": string
  "customPrompt"?: string // 非必填
  "largeLanguageModelId": string (uuid)
}
```

**回應範例值**

```json
{
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "largeLanguageModelId": "550e8400-e29b-41d4-a716-446655440000"
}
```

***

### 列出檔案翻譯 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`

#### 參數

| 參數名稱                  | 必填 | 類型      | 說明                                             |
| --------------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBaseFilePk` | ✅  | string  |                                                |
| `knowledgeBasePk`     | ✅  | string  |                                                |
| `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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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)
      "chatbotFileId": string (uuid)
      "chatbotFileFilename": string
      "organization": string (uuid)
      "largeLanguageModel": 
      {
        "id": string (uuid)
        "name": string
      }
      "sourceLanguage": string
      "targetLanguage": string
      "customPrompt": string // User-provided terminology/glossary rules
      "status": 
      {
      }
      "errorMessage": string
      "translatedFileUrl": string
      "bilingualFileUrl": string
      "processDuration": string
      "processingDurationSeconds": number (double)
      "pageCount": integer
      "originalWordCount": integer
      "translatedWordCount": integer
      "inputTokensUsed": integer
      "outputTokensUsed": integer
      "totalTokensUsed": integer
      "originalFileSize": integer
      "translatedFileSize": integer
      "bilingualFileSize": integer
      "llmTranslationDuration": string // Total time spent on LLM API calls
      "llmTranslationDurationSeconds": number (double)
      "llmCallCount": integer // Number of LLM API calls made
      "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
      "pdfParsingDuration": string // Time spent on PDF parsing and processing
      "pdfParsingDurationSeconds": number (double)
      "fileSavingDuration": string // Time spent on saving output files
      "fileSavingDurationSeconds": number (double)
      "startedAt": string (timestamp)
      "completedAt": string (timestamp)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
      "chatbotFileFilename": "回應字串",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "sourceLanguage": "回應字串",
      "targetLanguage": "回應字串",
      "customPrompt": "回應字串",
      "status": {},
      "errorMessage": "回應字串",
      "translatedFileUrl": "回應字串",
      "bilingualFileUrl": "回應字串",
      "processDuration": "回應字串",
      "processingDurationSeconds": 456,
      "pageCount": 456,
      "originalWordCount": 456,
      "translatedWordCount": 456,
      "inputTokensUsed": 456,
      "outputTokensUsed": 456,
      "totalTokensUsed": 456,
      "originalFileSize": 456,
      "translatedFileSize": 456,
      "bilingualFileSize": 456,
      "llmTranslationDuration": "回應字串",
      "llmTranslationDurationSeconds": 456,
      "llmCallCount": 456,
      "avgLlmCallDuration": 456,
      "pdfParsingDuration": "回應字串",
      "pdfParsingDurationSeconds": 456,
      "fileSavingDuration": "回應字串",
      "fileSavingDurationSeconds": 456,
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 列出檔案翻譯 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/`

#### 參數

| 參數名稱                  | 必填 | 類型      | 說明                                             |
| --------------------- | -- | ------- | ---------------------------------------------- |
| `knowledgeBaseFilePk` | ✅  | string  |                                                |
| `knowledgeBasePk`     | ✅  | string  |                                                |
| `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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/?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)
      "chatbotFileId": string (uuid)
      "chatbotFileFilename": string
      "organization": string (uuid)
      "largeLanguageModel": 
      {
        "id": string (uuid)
        "name": string
      }
      "sourceLanguage": string
      "targetLanguage": string
      "customPrompt": string // User-provided terminology/glossary rules
      "status": 
      {
      }
      "errorMessage": string
      "translatedFileUrl": string
      "bilingualFileUrl": string
      "processDuration": string
      "processingDurationSeconds": number (double)
      "pageCount": integer
      "originalWordCount": integer
      "translatedWordCount": integer
      "inputTokensUsed": integer
      "outputTokensUsed": integer
      "totalTokensUsed": integer
      "originalFileSize": integer
      "translatedFileSize": integer
      "bilingualFileSize": integer
      "llmTranslationDuration": string // Total time spent on LLM API calls
      "llmTranslationDurationSeconds": number (double)
      "llmCallCount": integer // Number of LLM API calls made
      "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
      "pdfParsingDuration": string // Time spent on PDF parsing and processing
      "pdfParsingDurationSeconds": number (double)
      "fileSavingDuration": string // Time spent on saving output files
      "fileSavingDurationSeconds": number (double)
      "startedAt": string (timestamp)
      "completedAt": string (timestamp)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
      "chatbotFileFilename": "回應字串",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "sourceLanguage": "回應字串",
      "targetLanguage": "回應字串",
      "customPrompt": "回應字串",
      "status": {},
      "errorMessage": "回應字串",
      "translatedFileUrl": "回應字串",
      "bilingualFileUrl": "回應字串",
      "processDuration": "回應字串",
      "processingDurationSeconds": 456,
      "pageCount": 456,
      "originalWordCount": 456,
      "translatedWordCount": 456,
      "inputTokensUsed": 456,
      "outputTokensUsed": 456,
      "totalTokensUsed": 456,
      "originalFileSize": 456,
      "translatedFileSize": 456,
      "bilingualFileSize": 456,
      "llmTranslationDuration": "回應字串",
      "llmTranslationDurationSeconds": 456,
      "llmCallCount": 456,
      "avgLlmCallDuration": 456,
      "pdfParsingDuration": "回應字串",
      "pdfParsingDurationSeconds": 456,
      "fileSavingDuration": "回應字串",
      "fileSavingDurationSeconds": 456,
      "startedAt": "回應字串",
      "completedAt": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}
```

***

### 取得特定翻譯 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbotFileId": string (uuid)
  "chatbotFileFilename": string
  "organization": string (uuid)
  "largeLanguageModel": 
  {
    "id": string (uuid)
    "name": string
  }
  "sourceLanguage": string
  "targetLanguage": string
  "customPrompt": string // User-provided terminology/glossary rules
  "status": 
  {
  }
  "errorMessage": string
  "translatedFileUrl": string
  "bilingualFileUrl": string
  "processDuration": string
  "processingDurationSeconds": number (double)
  "pageCount": integer
  "originalWordCount": integer
  "translatedWordCount": integer
  "inputTokensUsed": integer
  "outputTokensUsed": integer
  "totalTokensUsed": integer
  "originalFileSize": integer
  "translatedFileSize": integer
  "bilingualFileSize": integer
  "llmTranslationDuration": string // Total time spent on LLM API calls
  "llmTranslationDurationSeconds": number (double)
  "llmCallCount": integer // Number of LLM API calls made
  "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
  "pdfParsingDuration": string // Time spent on PDF parsing and processing
  "pdfParsingDurationSeconds": number (double)
  "fileSavingDuration": string // Time spent on saving output files
  "fileSavingDurationSeconds": number (double)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileFilename": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "status": {},
  "errorMessage": "回應字串",
  "translatedFileUrl": "回應字串",
  "bilingualFileUrl": "回應字串",
  "processDuration": "回應字串",
  "processingDurationSeconds": 456,
  "pageCount": 456,
  "originalWordCount": 456,
  "translatedWordCount": 456,
  "inputTokensUsed": 456,
  "outputTokensUsed": 456,
  "totalTokensUsed": 456,
  "originalFileSize": 456,
  "translatedFileSize": 456,
  "bilingualFileSize": 456,
  "llmTranslationDuration": "回應字串",
  "llmTranslationDurationSeconds": 456,
  "llmCallCount": 456,
  "avgLlmCallDuration": 456,
  "pdfParsingDuration": "回應字串",
  "pdfParsingDurationSeconds": 456,
  "fileSavingDuration": "回應字串",
  "fileSavingDurationSeconds": 456,
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 取得特定翻譯 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbotFileId": string (uuid)
  "chatbotFileFilename": string
  "organization": string (uuid)
  "largeLanguageModel": 
  {
    "id": string (uuid)
    "name": string
  }
  "sourceLanguage": string
  "targetLanguage": string
  "customPrompt": string // User-provided terminology/glossary rules
  "status": 
  {
  }
  "errorMessage": string
  "translatedFileUrl": string
  "bilingualFileUrl": string
  "processDuration": string
  "processingDurationSeconds": number (double)
  "pageCount": integer
  "originalWordCount": integer
  "translatedWordCount": integer
  "inputTokensUsed": integer
  "outputTokensUsed": integer
  "totalTokensUsed": integer
  "originalFileSize": integer
  "translatedFileSize": integer
  "bilingualFileSize": integer
  "llmTranslationDuration": string // Total time spent on LLM API calls
  "llmTranslationDurationSeconds": number (double)
  "llmCallCount": integer // Number of LLM API calls made
  "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
  "pdfParsingDuration": string // Time spent on PDF parsing and processing
  "pdfParsingDurationSeconds": number (double)
  "fileSavingDuration": string // Time spent on saving output files
  "fileSavingDurationSeconds": number (double)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileFilename": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "status": {},
  "errorMessage": "回應字串",
  "translatedFileUrl": "回應字串",
  "bilingualFileUrl": "回應字串",
  "processDuration": "回應字串",
  "processingDurationSeconds": 456,
  "pageCount": 456,
  "originalWordCount": 456,
  "translatedWordCount": 456,
  "inputTokensUsed": 456,
  "outputTokensUsed": 456,
  "totalTokensUsed": 456,
  "originalFileSize": 456,
  "translatedFileSize": 456,
  "bilingualFileSize": 456,
  "llmTranslationDuration": "回應字串",
  "llmTranslationDurationSeconds": 456,
  "llmCallCount": 456,
  "avgLlmCallDuration": 456,
  "pdfParsingDuration": "回應字串",
  "pdfParsingDurationSeconds": 456,
  "fileSavingDuration": "回應字串",
  "fileSavingDurationSeconds": 456,
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 刪除翻譯 <a href="#undefined" id="undefined"></a>

DELETE `/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除翻譯 <a href="#undefined" id="undefined"></a>

DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 下載翻譯檔案 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/download/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/" \
  -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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbotFileId": string (uuid)
  "chatbotFileFilename": string
  "organization": string (uuid)
  "largeLanguageModel": 
  {
    "id": string (uuid)
    "name": string
  }
  "sourceLanguage": string
  "targetLanguage": string
  "customPrompt": string // User-provided terminology/glossary rules
  "status": 
  {
  }
  "errorMessage": string
  "translatedFileUrl": string
  "bilingualFileUrl": string
  "processDuration": string
  "processingDurationSeconds": number (double)
  "pageCount": integer
  "originalWordCount": integer
  "translatedWordCount": integer
  "inputTokensUsed": integer
  "outputTokensUsed": integer
  "totalTokensUsed": integer
  "originalFileSize": integer
  "translatedFileSize": integer
  "bilingualFileSize": integer
  "llmTranslationDuration": string // Total time spent on LLM API calls
  "llmTranslationDurationSeconds": number (double)
  "llmCallCount": integer // Number of LLM API calls made
  "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
  "pdfParsingDuration": string // Time spent on PDF parsing and processing
  "pdfParsingDurationSeconds": number (double)
  "fileSavingDuration": string // Time spent on saving output files
  "fileSavingDurationSeconds": number (double)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileFilename": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "status": {},
  "errorMessage": "回應字串",
  "translatedFileUrl": "回應字串",
  "bilingualFileUrl": "回應字串",
  "processDuration": "回應字串",
  "processingDurationSeconds": 456,
  "pageCount": 456,
  "originalWordCount": 456,
  "translatedWordCount": 456,
  "inputTokensUsed": 456,
  "outputTokensUsed": 456,
  "totalTokensUsed": 456,
  "originalFileSize": 456,
  "translatedFileSize": 456,
  "bilingualFileSize": 456,
  "llmTranslationDuration": "回應字串",
  "llmTranslationDurationSeconds": 456,
  "llmCallCount": 456,
  "avgLlmCallDuration": 456,
  "pdfParsingDuration": "回應字串",
  "pdfParsingDurationSeconds": 456,
  "fileSavingDuration": "回應字串",
  "fileSavingDurationSeconds": 456,
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 下載翻譯檔案 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/download/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", 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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/550e8400-e29b-41d4-a716-446655440000/download/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "chatbotFileId": string (uuid)
  "chatbotFileFilename": string
  "organization": string (uuid)
  "largeLanguageModel": 
  {
    "id": string (uuid)
    "name": string
  }
  "sourceLanguage": string
  "targetLanguage": string
  "customPrompt": string // User-provided terminology/glossary rules
  "status": 
  {
  }
  "errorMessage": string
  "translatedFileUrl": string
  "bilingualFileUrl": string
  "processDuration": string
  "processingDurationSeconds": number (double)
  "pageCount": integer
  "originalWordCount": integer
  "translatedWordCount": integer
  "inputTokensUsed": integer
  "outputTokensUsed": integer
  "totalTokensUsed": integer
  "originalFileSize": integer
  "translatedFileSize": integer
  "bilingualFileSize": integer
  "llmTranslationDuration": string // Total time spent on LLM API calls
  "llmTranslationDurationSeconds": number (double)
  "llmCallCount": integer // Number of LLM API calls made
  "avgLlmCallDuration": number (double) // Average time per LLM call in seconds
  "pdfParsingDuration": string // Time spent on PDF parsing and processing
  "pdfParsingDurationSeconds": number (double)
  "fileSavingDuration": string // Time spent on saving output files
  "fileSavingDurationSeconds": number (double)
  "startedAt": string (timestamp)
  "completedAt": string (timestamp)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
  "chatbotFileFilename": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "sourceLanguage": "回應字串",
  "targetLanguage": "回應字串",
  "customPrompt": "回應字串",
  "status": {},
  "errorMessage": "回應字串",
  "translatedFileUrl": "回應字串",
  "bilingualFileUrl": "回應字串",
  "processDuration": "回應字串",
  "processingDurationSeconds": 456,
  "pageCount": 456,
  "originalWordCount": 456,
  "translatedWordCount": 456,
  "inputTokensUsed": 456,
  "outputTokensUsed": 456,
  "totalTokensUsed": 456,
  "originalFileSize": 456,
  "translatedFileSize": 456,
  "bilingualFileSize": 456,
  "llmTranslationDuration": "回應字串",
  "llmTranslationDurationSeconds": 456,
  "llmCallCount": 456,
  "avgLlmCallDuration": 456,
  "pdfParsingDuration": "回應字串",
  "pdfParsingDurationSeconds": 456,
  "fileSavingDuration": "回應字串",
  "fileSavingDurationSeconds": 456,
  "startedAt": "回應字串",
  "completedAt": "回應字串",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 列出知識庫文件 <a href="#undefined" id="undefined"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/documents/`

#### 參數

| 參數名稱                  | 必填 | 類型     | 說明                                        |
| --------------------- | -- | ------ | ----------------------------------------- |
| `knowledgeBasePk`     | ✅  | string |                                           |
| `chatbotFileId`       | ❌  | string | 【將棄用】檔案 ID（請使用 knowledge\_base\_file\_id） |
| `knowledgeBaseFileId` | ❌  | string | 知識庫檔案 ID                                  |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "fileName": string
    "pageNumber"?: integer // 非必填
    "chatbotFile": string (uuid)
    "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
    "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
    "llamaIndexObjectJson"?: object // 非必填
    "metadata"?: object // 非必填
    "text": string
    "updatedAt": string (timestamp)
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "回應字串",
    "pageNumber": 456,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "回應字串",
    "updatedAt": "回應字串"
  }
]
```

***

### 列出知識庫文件 <a href="#undefined" id="undefined"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/`

#### 參數

| 參數名稱                  | 必填 | 類型     | 說明                                        |
| --------------------- | -- | ------ | ----------------------------------------- |
| `knowledgeBasePk`     | ✅  | string |                                           |
| `chatbotFileId`       | ❌  | string | 【將棄用】檔案 ID（請使用 knowledge\_base\_file\_id） |
| `knowledgeBaseFileId` | ❌  | string | 知識庫檔案 ID                                  |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/?chatbotFileId=example&knowledgeBaseFileId=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "fileName": string
    "pageNumber"?: integer // 非必填
    "chatbotFile": string (uuid)
    "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
    "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
    "llamaIndexObjectJson"?: object // 非必填
    "metadata"?: object // 非必填
    "text": string
    "updatedAt": string (timestamp)
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "回應字串",
    "pageNumber": 456,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "回應字串",
    "updatedAt": "回應字串"
  }
]
```

***

### 更新文件 <a href="#undefined" id="undefined"></a>

PUT `/api/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                        | 類型            | 必填 | 說明                                          |
| ------------------------- | ------------- | -- | ------------------------------------------- |
| fileName                  | string        | 是  |                                             |
| pageNumber                | integer       | 否  |                                             |
| chatbotFile               | string (uuid) | 是  |                                             |
| excludedEmbedMetadataKeys | object        | 否  | List\[str]: 不要包含在 embedding 中的 metadata 鍵列表 |
| excludedLlmMetadataKeys   | object        | 否  | List\[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表    |
| llamaIndexObjectJson      | object        | 否  |                                             |
| metadata                  | object        | 否  |                                             |
| text                      | string        | 是  |                                             |

**請求結構範例**

```typescript
{
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
}
```

**請求範例值**

```json
{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  }'

# 請確認在執行前替換 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 = {
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "fileName": "範例字串",
      "pageNumber": 123,
      "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
      "excludedEmbedMetadataKeys": null,
      "excludedLlmMetadataKeys": null,
      "llamaIndexObjectJson": null,
      "metadata": null,
      "text": "這是一個範例訊息"
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "fileName": "範例字串",
            "pageNumber": 123,
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "excludedEmbedMetadataKeys": null,
            "excludedLlmMetadataKeys": null,
            "llamaIndexObjectJson": null,
            "metadata": null,
            "text": "這是一個範例訊息"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "回應字串",
  "pageNumber": 456,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 更新文件 <a href="#undefined" id="undefined"></a>

PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                        | 類型            | 必填 | 說明                                          |
| ------------------------- | ------------- | -- | ------------------------------------------- |
| fileName                  | string        | 是  |                                             |
| pageNumber                | integer       | 否  |                                             |
| chatbotFile               | string (uuid) | 是  |                                             |
| excludedEmbedMetadataKeys | object        | 否  | List\[str]: 不要包含在 embedding 中的 metadata 鍵列表 |
| excludedLlmMetadataKeys   | object        | 否  | List\[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表    |
| llamaIndexObjectJson      | object        | 否  |                                             |
| metadata                  | object        | 否  |                                             |
| text                      | string        | 是  |                                             |

**請求結構範例**

```typescript
{
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
}
```

**請求範例值**

```json
{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  }'

# 請確認在執行前替換 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 = {
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "fileName": "範例字串",
      "pageNumber": 123,
      "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
      "excludedEmbedMetadataKeys": null,
      "excludedLlmMetadataKeys": null,
      "llamaIndexObjectJson": null,
      "metadata": null,
      "text": "這是一個範例訊息"
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "fileName": "範例字串",
            "pageNumber": 123,
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "excludedEmbedMetadataKeys": null,
            "excludedLlmMetadataKeys": null,
            "llamaIndexObjectJson": null,
            "metadata": null,
            "text": "這是一個範例訊息"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "回應字串",
  "pageNumber": 456,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 部分更新文件 <a href="#undefined" id="undefined"></a>

PATCH `/api/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                        | 類型            | 必填 | 說明                                          |
| ------------------------- | ------------- | -- | ------------------------------------------- |
| fileName                  | string        | 否  |                                             |
| pageNumber                | integer       | 否  |                                             |
| chatbotFile               | string (uuid) | 否  |                                             |
| excludedEmbedMetadataKeys | object        | 否  | List\[str]: 不要包含在 embedding 中的 metadata 鍵列表 |
| excludedLlmMetadataKeys   | object        | 否  | List\[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表    |
| llamaIndexObjectJson      | object        | 否  |                                             |
| metadata                  | object        | 否  |                                             |
| text                      | string        | 否  |                                             |

**請求結構範例**

```typescript
{
  "fileName"?: string // 非必填
  "pageNumber"?: integer // 非必填
  "chatbotFile"?: string (uuid) // 非必填
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text"?: string // 非必填
}
```

**請求範例值**

```json
{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  }'

# 請確認在執行前替換 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 = {
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  };

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "fileName": "範例字串",
      "pageNumber": 123,
      "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
      "excludedEmbedMetadataKeys": null,
      "excludedLlmMetadataKeys": null,
      "llamaIndexObjectJson": null,
      "metadata": null,
      "text": "這是一個範例訊息"
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "fileName": "範例字串",
            "pageNumber": 123,
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "excludedEmbedMetadataKeys": null,
            "excludedLlmMetadataKeys": null,
            "llamaIndexObjectJson": null,
            "metadata": null,
            "text": "這是一個範例訊息"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "回應字串",
  "pageNumber": 456,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 部分更新文件 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                        | 類型            | 必填 | 說明                                          |
| ------------------------- | ------------- | -- | ------------------------------------------- |
| fileName                  | string        | 否  |                                             |
| pageNumber                | integer       | 否  |                                             |
| chatbotFile               | string (uuid) | 否  |                                             |
| excludedEmbedMetadataKeys | object        | 否  | List\[str]: 不要包含在 embedding 中的 metadata 鍵列表 |
| excludedLlmMetadataKeys   | object        | 否  | List\[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表    |
| llamaIndexObjectJson      | object        | 否  |                                             |
| metadata                  | object        | 否  |                                             |
| text                      | string        | 否  |                                             |

**請求結構範例**

```typescript
{
  "fileName"?: string // 非必填
  "pageNumber"?: integer // 非必填
  "chatbotFile"?: string (uuid) // 非必填
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text"?: string // 非必填
}
```

**請求範例值**

```json
{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  }'

# 請確認在執行前替換 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 = {
    "fileName": "範例字串",
    "pageNumber": 123,
    "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
    "excludedEmbedMetadataKeys": null,
    "excludedLlmMetadataKeys": null,
    "llamaIndexObjectJson": null,
    "metadata": null,
    "text": "這是一個範例訊息"
  };

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "fileName": "範例字串",
      "pageNumber": 123,
      "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
      "excludedEmbedMetadataKeys": null,
      "excludedLlmMetadataKeys": null,
      "llamaIndexObjectJson": null,
      "metadata": null,
      "text": "這是一個範例訊息"
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "fileName": "範例字串",
            "pageNumber": 123,
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "excludedEmbedMetadataKeys": null,
            "excludedLlmMetadataKeys": null,
            "llamaIndexObjectJson": null,
            "metadata": null,
            "text": "這是一個範例訊息"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "fileName": string
  "pageNumber"?: integer // 非必填
  "chatbotFile": string (uuid)
  "excludedEmbedMetadataKeys"?: object // List[str]: 不要包含在 embedding 中的 metadata 鍵列表 (非必填)
  "excludedLlmMetadataKeys"?: object // List[str]: 不要包含在 LLM 上下文中的 metadata 鍵列表 (非必填)
  "llamaIndexObjectJson"?: object // 非必填
  "metadata"?: object // 非必填
  "text": string
  "updatedAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "回應字串",
  "pageNumber": 456,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "回應字串",
  "updatedAt": "回應字串"
}
```

***

### 刪除文件 <a href="#undefined" id="undefined"></a>

DELETE `/api/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除文件 <a href="#undefined" id="undefined"></a>

DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/documents/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 建立新的 FAQ <a href="#faq" id="faq"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/faqs/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 是  |                        |
| answer                | string                     | 是  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 建立新的 FAQ <a href="#faq" id="faq"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 是  |                        |
| answer                | string                     | 是  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 批量刪除 FAQ <a href="#faq" id="faq"></a>

POST `/api/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位  | 類型             | 必填 | 說明 |
| --- | -------------- | -- | -- |
| ids | array\[string] | 否  |    |

**請求結構範例**

```typescript
{
  "ids"?: [ // 非必填
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 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 = {
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.post("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "ids": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "ids": [
                "550e8400-e29b-41d4-a716-446655440000"
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 批量刪除 FAQ <a href="#faq" id="faq"></a>

POST `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete/`

#### 參數

| 參數名稱              | 必填 | 類型     | 說明 |
| ----------------- | -- | ------ | -- |
| `knowledgeBasePk` | ✅  | string |    |

#### 請求內容

**請求參數**

| 欄位  | 類型             | 必填 | 說明 |
| --- | -------------- | -- | -- |
| ids | array\[string] | 否  |    |

**請求結構範例**

```typescript
{
  "ids"?: [ // 非必填
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 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 = {
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "ids": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }

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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "ids": [
                "550e8400-e29b-41d4-a716-446655440000"
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 列出特定知識庫的所有 FAQ <a href="#faq" id="faq"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/faqs/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                      |
| ----------------- | -- | ------- | ------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                         |
| `page`            | ❌  | integer | A page number within the paginated result set.          |
| `pageSize`        | ❌  | integer | Number of results to return per page.                   |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：FAQ ID、問題、答案、標籤名稱、Metadata value |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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 (非必填)
      "hitsCount": integer
      "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "knowledgeBase"?:  // 非必填
      {
        "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": "回應字串"
      }
    }
  ]
}
```

***

### 列出特定知識庫的所有 FAQ <a href="#faq" id="faq"></a>

GET `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/`

#### 參數

| 參數名稱              | 必填 | 類型      | 說明                                                      |
| ----------------- | -- | ------- | ------------------------------------------------------- |
| `knowledgeBasePk` | ✅  | string  |                                                         |
| `page`            | ❌  | integer | A page number within the paginated result set.          |
| `pageSize`        | ❌  | integer | Number of results to return per page.                   |
| `query`           | ❌  | string  | 搜尋關鍵字，支援空白分隔的多條件查詢。可搜尋：FAQ ID、問題、答案、標籤名稱、Metadata value |

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\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 (非必填)
      "hitsCount": integer
      "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "knowledgeBase"?:  // 非必填
      {
        "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": "回應字串"
      }
    }
  ]
}
```

***

### 取得特定 FAQ 詳情 <a href="#faq" id="faq"></a>

GET `/api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 取得特定 FAQ 詳情 <a href="#faq" id="faq"></a>

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

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 更新 FAQ <a href="#faq" id="faq"></a>

PUT `/api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 是  |                        |
| answer                | string                     | 是  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

response = requests.put(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->put("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 更新 FAQ <a href="#faq" id="faq"></a>

PUT `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 是  |                        |
| answer                | string                     | 是  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

response = requests.put(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->put("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 部分更新 FAQ <a href="#faq" id="faq"></a>

PATCH `/api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 否  |                        |
| answer                | string                     | 否  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question"?: string // 非必填
  "answer"?: string // 非必填
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 部分更新 FAQ <a href="#faq" id="faq"></a>

PATCH `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 請求內容

**請求參數**

| 欄位                    | 類型                         | 必填 | 說明                     |
| --------------------- | -------------------------- | -- | ---------------------- |
| question              | string                     | 否  |                        |
| answer                | string                     | 否  |                        |
| answerMediaUrls       | object                     | 否  | 存放答案中的圖片、影片等媒體檔案的 URLs |
| labels                | array\[IdName]             | 否  |                        |
| rawUserDefineMetadata | object                     | 否  |                        |
| knowledgeBase         | object (含 2 個屬性: id, name) | 否  |                        |
| knowledgeBase.id      | string (uuid)              | 是  |                        |

**請求結構範例**

```typescript
{
  "question"?: string // 非必填
  "answer"?: string // 非必填
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}
```

**請求範例值**

```json
{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# 請確認在執行前替換 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 = {
    "question": "範例字串",
    "answer": "範例字串",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  };

axios.patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "question": "範例字串",
      "answer": "範例字串",
      "answerMediaUrls": null,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "question": "範例字串",
            "answer": "範例字串",
            "answerMediaUrls": null,
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "rawUserDefineMetadata": null,
            "knowledgeBase": {
                "id": "550e8400-e29b-41d4-a716-446655440000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "hitsCount": integer
  "embeddingTokensCount": integer // 建立此 FAQ 時使用的 embedding tokens 數量
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
    "name": string
  }
}
```

**回應範例值**

```json
{
  "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": "回應字串"
  }
}
```

***

### 刪除 FAQ <a href="#faq" id="faq"></a>

DELETE `/api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/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'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除 FAQ <a href="#faq" id="faq"></a>

DELETE `/api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/`

#### 參數

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

#### 程式碼範例

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

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

{% endtab %}

{% tab title="JavaScript" %}

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

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

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    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->delete("https://api.maiagent.ai/api/v1/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***


---

# Agent Instructions: 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:

```
GET https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.