知識庫（新版）

建立知識庫

POST /api/v1/knowledge-bases/

請求內容

請求參數

欄位	類型	必填	說明
embeddingModel	string (uuid)	是
rerankerModel	string (uuid)	是
name	string	是
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
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]	否

請求結構範例

{
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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)
    }
  ]
}

請求範例值

{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 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"
    }
  ]
}

程式碼範例

Shell/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,
    "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"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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
  "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)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 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,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

列出所有知識庫

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "createdBy": 
      {
        "id": string (uuid)
        "name": string
      }
      "organization"?: string (uuid) // 非必填
      "embeddingModel": string (uuid)
      "rerankerModel": string (uuid)
      "name": string
      "description"?: string // 非必填
      "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
      "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
      "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)
    }
  ]
}

回應範例值

{
  "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": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "numberOfRetrievedChunks": 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,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

取得特定知識庫詳情

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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
  "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)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 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,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

更新知識庫

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
organization	string (uuid)	否
embeddingModel	string (uuid)	是
rerankerModel	string (uuid)	是
name	string	是
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
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]	否	知識庫可存取的群組列表

請求結構範例

{
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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)
    }
  ]
}

請求範例值

{
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 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"
    }
  ]
}

程式碼範例

Shell/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 '{
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 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"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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
  "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)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 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,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

部分更新知識庫

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
organization	string (uuid)	否
embeddingModel	string (uuid)	否
rerankerModel	string (uuid)	否
name	string	否
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
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]	否	知識庫可存取的群組列表

請求結構範例

{
  "organization"?: string (uuid) // 非必填
  "embeddingModel"?: string (uuid) // 非必填
  "rerankerModel"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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)
    }
  ]
}

請求範例值

{
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 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"
    }
  ]
}

程式碼範例

Shell/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 '{
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 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"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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
  "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)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 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,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除知識庫

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

檢查 RRF 可用性

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "createdBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "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
  "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)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 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,
  "canUpdate": false,
  "canDelete": false,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

匯出標籤 Excel

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
200	Excel file download

---

匯入標籤 Excel

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

匯出元資料 Excel

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
200	Excel 檔案下載

---

匯入元資料 Excel

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

建立新標籤

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
name	string	是

請求結構範例

{
  "name": string
}

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

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

回應範例值

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

---

列出知識庫中的標籤

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.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name"?: string // 非必填
    }
  ]
}

回應範例值

{
  "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": "回應字串"
    }
  ]
}

---

取得特定標籤詳情

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

更新標籤

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
name	string	是

請求結構範例

{
  "name": string
}

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

部分更新標籤

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
name	string	否

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

刪除標籤

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

建立元資料欄位

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

參數

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

請求內容

請求參數

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

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "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)
}

回應範例值

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

---

列出元資料欄位

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.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
    }
  ]
}

回應範例值

{
  "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": "回應字串"
    }
  ]
}

---

取得特定元資料欄位

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

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

---

更新元資料欄位

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	否	是否在檢索時使用此欄位

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

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

---

上傳檔案到知識庫

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 個檔案

請求結構範例

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

請求範例值

{
  "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"
    }
  ]
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "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 // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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,
        "supportsDiarization": false,
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}

---

批量刪除檔案

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

參數

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

請求內容

請求參數

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

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

批量重新解析檔案

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" %}

# 呼叫 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 並核對請求資料。

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);
  });

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
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

回應結構範例

{
  "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 // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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,
        "supportsDiarization": false,
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}

---

列出知識庫中的檔案

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" %}

# 呼叫 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 並核對請求資料。

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);
  });

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
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

回應結構範例

{
  "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 // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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,
        "supportsDiarization": false,
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ]
}

---

取得特定檔案詳情

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 非必填
    "supportsDiarization": boolean
    "isTimestampSttProvider": boolean
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "speakerLabels": [
    {
      "id": string (uuid)
      "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
      "customName"?: string // User-defined speaker name (e.g., John) (非必填)
      "displayName": string
    }
  ]
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "waitingTime": number (double)
  "processingTime": number (double)
  "processingTimeDetails": object
  "createdAt": string (timestamp)
}

回應範例值

{
  "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,
    "supportsDiarization": false,
    "isTimestampSttProvider": false
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "speakerLabels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "originalLabel": "回應字串",
      "customName": "回應字串",
      "displayName": "回應字串"
    }
  ],
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}

---

取得檔案最新失敗原因

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

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

---

取得檔案轉錄內容

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 非必填
    "supportsDiarization": boolean
    "isTimestampSttProvider": boolean
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "speakerLabels": [
    {
      "id": string (uuid)
      "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
      "customName"?: string // User-defined speaker name (e.g., John) (非必填)
      "displayName": string
    }
  ]
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "waitingTime": number (double)
  "processingTime": number (double)
  "processingTimeDetails": object
  "createdAt": string (timestamp)
}

回應範例值

{
  "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,
    "supportsDiarization": false,
    "isTimestampSttProvider": false
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "speakerLabels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "originalLabel": "回應字串",
      "customName": "回應字串",
      "displayName": "回應字串"
    }
  ],
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}

---

更新檔案資訊

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	否

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 非必填
    "supportsDiarization": boolean
    "isTimestampSttProvider": boolean
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "speakerLabels": [
    {
      "id": string (uuid)
      "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
      "customName"?: string // User-defined speaker name (e.g., John) (非必填)
      "displayName": string
    }
  ]
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "waitingTime": number (double)
  "processingTime": number (double)
  "processingTimeDetails": object
  "createdAt": string (timestamp)
}

回應範例值

{
  "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,
    "supportsDiarization": false,
    "isTimestampSttProvider": false
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "speakerLabels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "originalLabel": "回應字串",
      "customName": "回應字串",
      "displayName": "回應字串"
    }
  ],
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}

---

部分更新檔案

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	否

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 非必填
    "supportsDiarization": boolean
    "isTimestampSttProvider": boolean
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "speakerLabels": [
    {
      "id": string (uuid)
      "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
      "customName"?: string // User-defined speaker name (e.g., John) (非必填)
      "displayName": string
    }
  ]
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "waitingTime": number (double)
  "processingTime": number (double)
  "processingTimeDetails": object
  "createdAt": string (timestamp)
}

回應範例值

{
  "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,
    "supportsDiarization": false,
    "isTimestampSttProvider": false
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "speakerLabels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "originalLabel": "回應字串",
      "customName": "回應字串",
      "displayName": "回應字串"
    }
  ],
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "waitingTime": 456,
  "processingTime": 456,
  "processingTimeDetails": null,
  "createdAt": "回應字串"
}

---

刪除檔案

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

建立檔案翻譯

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

參數

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

請求內容

請求參數

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

請求結構範例

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

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

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

回應範例值

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

---

列出檔案翻譯

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.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
    }
  ]
}

回應範例值

{
  "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": "回應字串"
    }
  ]
}

---

取得特定翻譯

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

{
  "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": "回應字串"
}

---

刪除翻譯

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

下載翻譯檔案

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

參數

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

{
  "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": "回應字串"
}

---

列出知識庫文件

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

參數

參數名稱	必填	類型	說明
knowledgeBasePk	✅	string
chatbotFileId	❌	string	【將棄用】檔案 ID（請使用 knowledge_base_file_id）
knowledgeBaseFileId	❌	string	知識庫檔案 ID

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "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)
  }
]

回應範例值

[
  {
    "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": "回應字串"
  }
]

---

更新文件

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	是

請求結構範例

{
  "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
}

請求範例值

{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

{
  "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": "回應字串"
}

---

部分更新文件

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	否

請求結構範例

{
  "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 // 非必填
}

請求範例值

{
  "fileName": "範例字串",
  "pageNumber": 123,
  "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
  "excludedEmbedMetadataKeys": null,
  "excludedLlmMetadataKeys": null,
  "llamaIndexObjectJson": null,
  "metadata": null,
  "text": "這是一個範例訊息"
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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)
}

回應範例值

{
  "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": "回應字串"
}

---

刪除文件

DELETE /api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot 文件.
knowledgeBasePk	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

建立新的 FAQ

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)	是

請求結構範例

{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}

請求範例值

{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "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
  }
}

回應範例值

{
  "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

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
ids	array[string]	否

請求結構範例

{
  "ids"?: [ // 非必填
    string (uuid)
  ]
}

請求範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

列出特定知識庫的所有 FAQ

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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
      }
    }
  ]
}

回應範例值

{
  "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 詳情

GET /api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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
  }
}

回應範例值

{
  "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

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)	是

請求結構範例

{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}

請求範例值

{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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
  }
}

回應範例值

{
  "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

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)	是

請求結構範例

{
  "question"?: string // 非必填
  "answer"?: string // 非必填
  "answerMediaUrls"?: object // 存放答案中的圖片、影片等媒體檔案的 URLs (非必填)
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "knowledgeBase"?:  // 非必填
  {
    "id": string (uuid)
  }
}

請求範例值

{
  "question": "範例字串",
  "answer": "範例字串",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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
  }
}

回應範例值

{
  "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

DELETE /api/v1/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---