API 總覽說明

文件概述

Documentation of API endpoints of MaiAgent

API 分類與端點列表

AI 助理

• POST api/chatbots: 建立新 AI 助理

• GET api/chatbot-settings: 列出 AI 助理有的設定項目

• GET api/embedding-models: 列出 Embedding Model

• GET api/reranker-models: 列出 Reranker Model

• GET api/chatbots: 取得 AI 助理列表

• GET api/chatbots/{id}: 取得特定 AI 助理

• PUT api/chatbots/{id}: 更新 AI 助理

• PATCH api/chatbots/{id}: 部分更新 AI 助理

• DELETE api/chatbots/{id}: 刪除 AI 助理

附件與檔案

• POST api/attachments-upload: 建立新附件 (整合)

• POST api/upload-presigned-url: 取得檔案上傳用的預簽署 URL (建立/取得)

• POST api/attachments: Presigned 上傳附件

• POST api/conversations/{conversationPk}/attachments: 建立對話附件

知識庫（新版）

• POST api/knowledge-bases: 建立知識庫

• GET api/knowledge-bases: 列出所有知識庫

• GET api/knowledge-bases/{id}: 取得特定知識庫詳情

• GET api/knowledge-bases/{id}/search: 搜尋特定知識庫的內容

• PUT api/knowledge-bases/{id}: 更新知識庫

• PATCH api/knowledge-bases/{id}: 部分更新知識庫

• DELETE api/knowledge-bases/{id}: 刪除知識庫

• POST api/knowledge-bases/{knowledgeBasePk}/labels: 創建新標籤

• GET api/knowledge-bases/{knowledgeBasePk}/labels: 列出知識庫中的標籤

• GET api/knowledge-bases/{knowledgeBasePk}/labels/{id}: 取得特定標籤詳情

• PUT api/knowledge-bases/{knowledgeBasePk}/labels/{id}: 更新標籤

• PATCH api/knowledge-bases/{knowledgeBasePk}/labels/{id}: 部分更新標籤

• DELETE api/knowledge-bases/{knowledgeBasePk}/labels/{id}: 刪除標籤

• POST api/knowledge-bases/{knowledgeBasePk}/files: 上傳檔案到知識庫

• POST api/knowledge-bases/{knowledgeBasePk}/files/{id}/update-metadata: 更新檔案元資料

• POST api/knowledge-bases/{knowledgeBasePk}/files/batch-delete: 批量刪除檔案

• GET api/knowledge-bases/{knowledgeBasePk}/files: 列出知識庫中的檔案

• GET api/knowledge-bases/{knowledgeBasePk}/files/{id}: 取得特定檔案詳情

• GET api/knowledge-bases/{knowledgeBasePk}/text-nodes: 列出知識庫中特定檔案的文字節點

• GET api/knowledge-bases/{knowledgeBasePk}/text-nodes/{id}: 取得特定文字節點詳情

• PUT api/knowledge-bases/{knowledgeBasePk}/files/{id}: 更新檔案資訊

• PATCH api/knowledge-bases/{knowledgeBasePk}/files/{id}: 部分更新檔案

• DELETE api/knowledge-bases/{knowledgeBasePk}/files/{id}: 刪除檔案

• POST api/knowledge-bases/{knowledgeBasePk}/faqs: 創建新的 FAQ

• POST api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/update-metadata: 更新 FAQ 元資料

• POST api/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete: 批量刪除 FAQ

• GET api/knowledge-bases/{knowledgeBasePk}/faqs: 列出特定知識庫的所有 FAQ

• GET api/knowledge-bases/{knowledgeBasePk}/faqs/{id}: 取得特定 FAQ 詳情

• PUT api/knowledge-bases/{knowledgeBasePk}/faqs/{id}: 更新 FAQ

• PATCH api/knowledge-bases/{knowledgeBasePk}/faqs/{id}: 部分更新 FAQ

• DELETE api/knowledge-bases/{knowledgeBasePk}/faqs/{id}: 刪除 FAQ

知識庫（舊版）

• POST api/chatbots/{chatbotPk}/files: 上傳新知識庫文件

• GET api/chatbots/{chatbotPk}/files: 取得知識庫文件列表

• GET api/chatbots/{chatbotPk}/files/{id}: 取得特定知識庫文件

• PUT api/chatbots/{chatbotPk}/files/{id}: 更新知識庫文件

• DELETE api/chatbots/{chatbotPk}/files/{id}: 刪除知識庫文件

• POST api/chatbots/{chatbotPk}/files/batch-delete: 批次刪除知識庫文件

• POST api/chatbots/{chatbotPk}/faqs: 建立新 FAQ

• GET api/chatbots/{chatbotPk}/faqs: 取得 FAQ 列表

• GET api/chatbots/{chatbotPk}/faqs/{id}: 取得特定 FAQ

• PUT api/chatbots/{chatbotPk}/faqs/{id}: 更新 FAQ

• DELETE api/chatbots/{chatbotPk}/faqs/{id}: 刪除 FAQ

• POST api/chatbots/{chatbotPk}/faqs/batch-delete: 批次刪除 FAQ

• GET api/chatbot-text-nodes: 取得 AI 助理的所有檔案的文本節點

• GET api/chatbot-text-nodes/{id}: 取得 AI 助理的特定檔案的文本節點

• POST api/chatbots/{id}/search: 搜尋測試

• GET api/parsers/supported-file-types: 列出檔案類型支援的解析器

對話與訊息

• POST api/chatbots/{chatbotId}/completions: 發送訊息 (串流)

• POST api/messages: 發送訊息 (建立)

• POST api/conversations: 建立新的對話

• GET api/messages: 取得訊息列表

• GET api/messages/{id}: 取得特定訊息

• GET api/conversations: 取得對話列表

• GET api/conversations/{id}: 取得特定對話

• GET api/chatbots/{chatbotPk}/records: 取得 AI 助理對話紀錄

• GET api/chatbots/{chatbotPk}/records/export-excel: 對話紀錄匯出為 Excel 檔案

對話 Widget

• GET api/web-chats/{id}: 取得特定 Web Chat

• GET api/chatbots/{chatbotPk}/llm-usage-statistics: 獲取 LLM 使用統計

• GET api/chatbots/{chatbotPk}/statistics: 取得 AI 助理統計數據

• PATCH api/chatbots/{chatbot_id}/enable-evaluation: 啟用或停用特定 AI 助理的評估功能

組織與成員

• POST api/auth/registration: 帳號註冊

• POST api/auth/password/change: 更換密碼

• POST api/organizations: 建立新組織

• POST api/organizations/{organizationPk}/members: 新增成員至指定組織

• GET api/organizations: 取得組織列表

• GET api/organizations/{id}: 取得特定組織資訊

• GET api/users/current: 取得當前用戶詳細資訊

• GET api/permissions: 取得當前用戶權限

• GET api/organizations/{organizationPk}/members: 取得指定組織的成員列表

• GET api/organizations/{organizationPk}/members/{id}: 取得特定成員詳細資訊

• PUT api/organizations/{id}: 更新組織資訊

• PUT api/users/current: 更新當前用戶詳細資訊

• PUT api/organizations/{organizationPk}/members/{id}: 更新指定組織成員資訊

• DELETE api/organizations/{id}: 刪除組織

• DELETE api/organizations/{organizationPk}/members/{id}: 刪除指定成員

角色與權限

• POST api/organizations/{organizationPk}/groups: 創建角色

• POST api/organizations/{organizationPk}/groups/{groupPk}/group-members/bulk-create: 批量新增角色成員

• POST api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/bulk-create: 批量分配 AI 助理給角色

• GET api/permissions: 列出權限清單

• GET api/organizations/{organizationPk}/groups: 獲取角色列表

• GET api/organizations/{organizationPk}/groups/{id}: 獲取角色的詳情

• GET api/organizations/{organizationPk}/groups/{groupPk}/group-members: 獲取角色成員列表

• GET api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}: 查看特定角色成員

• GET api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots: 獲取角色的 AI 助理列表

• PUT api/organizations/{organizationPk}/groups/{id}: 更新角色權限

• PATCH api/organizations/{organizationPk}/groups/{id}: 部分更新角色權限

• DELETE api/organizations/{organizationPk}/groups/{id}: 刪除角色

• DELETE api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}: 移除角色成員

• DELETE api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/{id}: 移除角色裡的 AI 助理

聯絡人

• GET api/contacts: 列出聯絡人

• POST api/contacts: 建立聯絡人

• GET api/contacts/{id}: 獲取聯絡人詳情

• PUT api/contacts/{id}: 更新聯絡人

• PATCH api/contacts/{id}: 更新聯絡人

• DELETE api/contacts/{id}: 刪除聯絡人

認證要求

所有 API 請求必須在 HTTP Header 中包含 API Key，格式如下：

Authorization: Api-Key YOUR_API_KEY

使用說明

• 請仔細閱讀每個端點的詳細文檔

• 在每個分類頁面中可以找到詳細的請求與回應格式

• 所有範例程式碼都提供了多種程式語言的版本

狀態碼說明

狀態碼	說明
200	請求成功
201	資源成功建立
400	請求格式錯誤
401	認證失敗
403	權限不足
404	資源不存在
500	伺服器錯誤