知識庫（新版）

建立知識庫

POST /api/knowledge-bases/

請求內容

請求參數

欄位	類型	必填	說明
embeddingModel	string (uuid)	是
rerankerModel	string (uuid)	是
name	string	是
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
sentenceWindowSize	integer	否	RAG 擴增句子視窗大小，預設為 2，最小值為 0
enableHyde	boolean	否	啟用 HyDE，預設為 False
similarityCutoff	number (double)	否	相似度門檻，預設為 0.0，範圍為 0.0-1.0
enableRerank	boolean	否	是否啟用重新排序，預設為 True
elasticsearchUrl	string (uri)	否	Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used.
elasticsearchApiKey	string	否	API Key for custom Elasticsearch endpoint. Will be stored securely.
chatbots	array[IdName]	否
groups	array[IdName]	否

請求結構範例

{
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "範例字串",
  "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/knowledge-bases/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "elasticsearchUrl": "https://example.com/file.jpg",
    "elasticsearchApiKey": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // 回傳此知識庫下的 KnowledgeBaseFile 數量（排除處理過的文件、對話附件和軟刪除的檔案）
  "vectorStorageSize": integer
  "chunksCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "回應字串",
  "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,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

列出所有知識庫

GET /api/knowledge-bases/

參數

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

程式碼範例

Shell/Bash

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

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "user"?: string (uuid) // 非必填
      "organization"?: string (uuid) // 非必填
      "embeddingModel": string (uuid)
      "rerankerModel": string (uuid)
      "name": string
      "description"?: string // 非必填
      "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
      "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
      "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
      "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
      "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
      "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
      "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
      "labels": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "chatbots"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "groups"?: [ // 知識庫可存取的群組列表 (非必填)
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "filesCount": integer // 回傳此知識庫下的 KnowledgeBaseFile 數量（排除處理過的文件、對話附件和軟刪除的檔案）
      "vectorStorageSize": integer
      "chunksCount": integer
      "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",
      "user": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "numberOfRetrievedChunks": 456,
      "sentenceWindowSize": 456,
      "enableHyde": false,
      "similarityCutoff": 456,
      "enableRerank": false,
      "elasticsearchUrl": "https://example.com/file.jpg",
      "elasticsearchApiKey": "回應字串",
      "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,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ]
}

---

取得特定知識庫詳情

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

參數

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

程式碼範例

Shell/Bash

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

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // 回傳此知識庫下的 KnowledgeBaseFile 數量（排除處理過的文件、對話附件和軟刪除的檔案）
  "vectorStorageSize": integer
  "chunksCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "回應字串",
  "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,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

更新知識庫

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
user	string (uuid)	否
organization	string (uuid)	否
embeddingModel	string (uuid)	是
rerankerModel	string (uuid)	是
name	string	是
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
sentenceWindowSize	integer	否	RAG 擴增句子視窗大小，預設為 2，最小值為 0
enableHyde	boolean	否	啟用 HyDE，預設為 False
similarityCutoff	number (double)	否	相似度門檻，預設為 0.0，範圍為 0.0-1.0
enableRerank	boolean	否	是否啟用重新排序，預設為 True
elasticsearchUrl	string (uri)	否	Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used.
elasticsearchApiKey	string	否	API Key for custom Elasticsearch endpoint. Will be stored securely.
chatbots	array[IdName]	否
groups	array[IdName]	否	知識庫可存取的群組列表

請求結構範例

{
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "範例字串",
  "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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "elasticsearchUrl": "https://example.com/file.jpg",
    "elasticsearchApiKey": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // 回傳此知識庫下的 KnowledgeBaseFile 數量（排除處理過的文件、對話附件和軟刪除的檔案）
  "vectorStorageSize": integer
  "chunksCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "回應字串",
  "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,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

部分更新知識庫

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
user	string (uuid)	否
organization	string (uuid)	否
embeddingModel	string (uuid)	否
rerankerModel	string (uuid)	否
name	string	否
description	string	否
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
sentenceWindowSize	integer	否	RAG 擴增句子視窗大小，預設為 2，最小值為 0
enableHyde	boolean	否	啟用 HyDE，預設為 False
similarityCutoff	number (double)	否	相似度門檻，預設為 0.0，範圍為 0.0-1.0
enableRerank	boolean	否	是否啟用重新排序，預設為 True
elasticsearchUrl	string (uri)	否	Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used.
elasticsearchApiKey	string	否	API Key for custom Elasticsearch endpoint. Will be stored securely.
chatbots	array[IdName]	否
groups	array[IdName]	否	知識庫可存取的群組列表

請求結構範例

{
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel"?: string (uuid) // 非必填
  "rerankerModel"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "範例名稱",
  "description": "範例字串",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "範例字串",
  "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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "範例名稱",
    "description": "範例字串",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "elasticsearchUrl": "https://example.com/file.jpg",
    "elasticsearchApiKey": "範例字串",
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

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

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "user"?: string (uuid) // 非必填
  "organization"?: string (uuid) // 非必填
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // 非必填
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
  "enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
  "similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
  "enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
  "elasticsearchUrl"?: string (uri) // Custom Elasticsearch endpoint URL. If not provided, the default system Elasticsearch will be used. (非必填)
  "elasticsearchApiKey"?: string // API Key for custom Elasticsearch endpoint. Will be stored securely. (非必填)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // 知識庫可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // 回傳此知識庫下的 KnowledgeBaseFile 數量（排除處理過的文件、對話附件和軟刪除的檔案）
  "vectorStorageSize": integer
  "chunksCount": integer
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "elasticsearchUrl": "https://example.com/file.jpg",
  "elasticsearchApiKey": "回應字串",
  "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,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除知識庫

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

參數

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

程式碼範例

Shell/Bash

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

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

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

創建新標籤

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

參數

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

請求內容

請求參數

欄位	類型	必填	說明
name	string	是

請求結構範例

{
  "name": string
}

請求範例值

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

程式碼範例

Shell/Bash

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

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

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

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

回應範例值

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

---

列出知識庫中的標籤

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

參數

參數名稱	必填	類型	說明
knowledgeBasePk	✅	string
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

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

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

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/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/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/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/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/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/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/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/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/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
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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
  -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 // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "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
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "createdAt": "回應字串"
    }
  ]
}

---

批量刪除檔案

POST /api/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/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

---

列出知識庫中的檔案

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

參數

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

程式碼範例

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

``bash

呼叫 API 示例 (Shell)

curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" -H "Authorization: Api-Key YOUR_API_KEY"

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

</div>

<div data-gb-custom-block data-tag="tab" data-title='JavaScript'>

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

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

axios.get("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted", 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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted"
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/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted", [
        '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 // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "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
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "createdAt": "回應字串"
    }
  ]
}

---

取得特定檔案詳情

GET /api/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/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 // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "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
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "createdAt": "回應字串"
}

---

更新檔案資訊

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

參數

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

請求內容

請求參數

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

請求結構範例

{
  "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/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 // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "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
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "createdAt": "回應字串"
}

---

部分更新檔案

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

參數

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

請求內容

請求參數

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

請求結構範例

{
  "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/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 // 非必填
  }
  }
  "labels"?: [ // 非必填
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // 非必填
  "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
  "chunksCount": integer // Number of chunks/nodes generated from this file
  "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
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "rawUserDefineMetadata": null,
  "vectorStorageSize": 456,
  "chunksCount": 456,
  "createdAt": "回應字串"
}

---

部分更新檔案

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

參數

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

程式碼範例

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

``bash

呼叫 API 示例 (Shell)

curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" -H "Authorization: Api-Key YOUR_API_KEY" -H "Content-Type: application/json" -d '[]'

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

</div>

<div data-gb-custom-block data-tag="tab" data-title='JavaScript'>

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

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

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

axios.patch("https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted", 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/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=deleted"
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/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=deleted", [
        '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 // 非必填
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "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
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "createdAt": "回應字串"
    }
  ]
}

---

刪除檔案

DELETE /api/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/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

---

創建新的 FAQ

POST /api/knowledge-bases/{knowledgeBasePk}/faqs/

參數

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

請求內容

請求參數

欄位	類型	必填	說明
question	string	是
answer	string	是
answerMediaUrls	object	否	存放答案中的圖片、影片等媒體檔案的 URLs
labels	array[IdName]	否
rawUserDefineMetadata	object	否
knowledgeBase	object (含 2 個屬性: id, name)	否
knowledgeBase.id	string (uuid)	是

請求結構範例

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

程式碼範例

Shell/Bash

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

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

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

---