總覽說明

文件概述

Documentation of API endpoints of MaiAgent

串接範例程式碼

若需參考 API 完整用例及程式碼，可至以下 Github Repository 查看：

• C# 範例

• Python 範例

GitHub - Playma-Co-Ltd/maiagent-api-examplesGitHub

API 分類與端點列表

AI 助理

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

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

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

• GET api/v1/large-language-models: 列出大型語言模型

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

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

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

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

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

• POST api/v1/chatbots/{id}/duplicate: 複製 AI 助理

• PATCH api/v1/chatbots/{id}/enable-evaluation: 啟用或停用評估功能

附件與檔案

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

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

• POST api/v1/attachments: Presigned 上傳附件

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

• GET api/v1/allowed-file-specs: 取得允許的檔案規格

知識庫（新版）

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

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

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

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

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

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

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

• GET api/v1/knowledge-bases/{id}/check-rrf-availability: 檢查 RRF 可用性

• GET api/v1/knowledge-bases/{id}/export-labels-excel: 匯出標籤 Excel

• POST api/v1/knowledge-bases/{id}/import-labels-excel: 匯入標籤 Excel

• GET api/v1/knowledge-bases/{id}/export-metadata-excel: 匯出元資料 Excel

• POST api/v1/knowledge-bases/{id}/import-metadata-excel: 匯入元資料 Excel

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

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

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

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

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

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

• POST api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys: 建立元資料欄位

• GET api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys: 列出元資料欄位

• GET api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}: 取得特定元資料欄位

• PUT api/v1/knowledge-bases/{knowledgeBasePk}/metadata-keys/{id}: 更新元資料欄位

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

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

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

• PATCH api/v1/knowledge-bases/{knowledgeBasePk}/files/batch-reparse: 批量重新解析檔案

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

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

• GET api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/latest-failed-reason: 取得檔案最新失敗原因

• GET api/v1/knowledge-bases/{knowledgeBasePk}/files/{id}/transcription: 取得檔案轉錄內容

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

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

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

• POST api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations: 建立檔案翻譯

• GET api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations: 列出檔案翻譯

• GET api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}: 取得特定翻譯

• DELETE api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}: 刪除翻譯

• GET api/v1/knowledge-bases/{knowledgeBasePk}/files/{knowledgeBaseFilePk}/translations/{id}/download: 下載翻譯檔案

• GET api/v1/knowledge-bases/{knowledgeBasePk}/documents: 列出知識庫文件

• PUT api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}: 更新文件

• PATCH api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}: 部分更新文件

• DELETE api/v1/knowledge-bases/{knowledgeBasePk}/documents/{id}: 刪除文件

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

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

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

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

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

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

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

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

知識庫（舊版）

• GET api/v1/chatbots/{id}/knowledge-bases-files: 取得 AI 助理的知識庫檔案列表

• GET api/v1/chatbots/{id}/knowledge-bases-faqs: 取得 AI 助理的知識庫 FAQ 列表

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

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

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

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

對話與訊息

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

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

• POST api/v1/messages/outgoing: 發送主動訊息

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

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

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

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

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

• PATCH api/v1/conversations/{id}/rename: 重新命名對話

• POST api/v1/conversations/{conversationPk}/share: 分享對話

• POST api/v1/conversations/{conversationPk}/share/quick: 快速分享對話

• GET api/v1/shared-conversations: 列出分享的對話

• GET api/v1/shared-conversations/{id}: 取得特定分享對話

• PATCH api/v1/shared-conversations/{id}: 更新分享對話

• DELETE api/v1/shared-conversations/{id}: 刪除分享對話

• POST api/v1/shared-conversations/{id}/fork: 複製分享對話

• GET api/v1/shared-conversations/my-shares: 取得我的分享列表

• POST api/v1/messages/{messagePk}/feedback: 建立訊息回饋

• PUT api/v1/messages/{messagePk}/feedback/{id}: 更新訊息回饋

• DELETE api/v1/messages/{messagePk}/feedback/{id}: 刪除訊息回饋

• GET api/v1/records: 取得對話紀錄列表

• GET api/v1/records/{id}: 取得特定對話紀錄

• POST api/v1/records/export-excel-requests: 建立對話紀錄匯出請求

• GET api/v1/records/export-excel-requests/{exportId}: 取得對話紀錄匯出狀態

對話 Widget

• POST api/v1/web-chats: 建立 Web Chat

• GET api/v1/web-chats: 列出 Web Chat

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

• PUT api/v1/web-chats/{id}: 更新 Web Chat

• PATCH api/v1/web-chats/{id}: 部分更新 Web Chat

• POST api/v1/web-chats/{id}/setup-contact-credentials: 設定聯絡人憑證

• POST api/v1/web-chats/{id}/voice-agent/token: 取得語音助理 Token

• POST api/v1/web-chats/{webchatPk}/batch-qas: 上傳批次 QA 檔案

• GET api/v1/web-chats/{webchatPk}/batch-qas/{id}/export-excel: 匯出批次 QA 為 Excel

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

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

組織與成員

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

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

• POST api/v1/organizations: 建立新組織

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

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

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

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

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

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

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

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

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

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

• POST api/v1/organizations/{organizationPk}/members/{id}/update-groups: 更新成員所屬角色

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

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

• GET api/v1/organizations/{organizationPk}/usage-statistics/members: 取得成員使用統計

• GET api/v1/organizations/{organizationPk}/usage-statistics/members/summary: 取得成員使用統計摘要

• GET api/v1/organizations/{organizationPk}/usage-statistics/chatbots: 取得 AI 助理使用統計

• GET api/v1/organizations/{organizationPk}/usage-statistics/chatbots/summary: 取得 AI 助理使用統計摘要

角色與權限

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

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

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

• POST api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/bulk-create: 批量分配收件匣給角色

• POST api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/bulk-create: 批量分配知識庫給角色

• POST api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/bulk-create: 批量分配資料庫給角色

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

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

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

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

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

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

• GET api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes: 取得角色的收件匣列表

• GET api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases: 取得角色的知識庫列表

• GET api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases: 取得角色的資料庫列表

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

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

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

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

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

• DELETE api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/{id}: 移除角色裡的收件匣

• DELETE api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/{id}: 移除角色裡的知識庫

• DELETE api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/{id}: 移除角色裡的資料庫

聯絡人

• GET api/v1/contacts: 列出聯絡人

• POST api/v1/contacts: 建立聯絡人

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

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

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

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

• GET api/v1/contacts/{id}/conversations: 取得聯絡人的對話列表

• GET api/v1/contacts/{id}/conversations/latest: 取得聯絡人最新對話

• POST api/v1/contacts/broadcast-message: 群發訊息

工具與連接器

• POST api/v1/tools: 建立工具

• GET api/v1/tools: 列出工具

• GET api/v1/tools/{id}: 取得特定工具

• PUT api/v1/tools/{id}: 更新工具

• PATCH api/v1/tools/{id}: 部分更新工具

• DELETE api/v1/tools/{id}: 刪除工具

• GET api/v1/tools/available-tools: 列出可用工具

• POST api/v1/connectors: 建立連接器

• GET api/v1/connectors: 列出連接器

• GET api/v1/connectors/{id}: 取得特定連接器

• PUT api/v1/connectors/{id}: 更新連接器

• PATCH api/v1/connectors/{id}: 部分更新連接器

• DELETE api/v1/connectors/{id}: 刪除連接器

• GET api/v1/connectors/{id}/authorized-members: 列出連接器授權成員

• DELETE api/v1/connectors/{id}/authorized-members/{memberId}: 移除連接器授權成員

• GET api/v1/mcp/registry: 列出 MCP 工具登錄

• GET api/v1/mcp/registry/{id}: 取得特定 MCP 工具登錄

技能

• POST api/v1/skills/upload: 上傳技能

• GET api/v1/skills: 列出技能

• GET api/v1/skills/{id}: 取得特定技能

• PUT api/v1/skills/{id}: 更新技能

• PATCH api/v1/skills/{id}: 部分更新技能

• DELETE api/v1/skills/{id}: 刪除技能

• GET api/v1/skills/{id}/export: 匯出技能

• POST api/v1/skills/{id}/reupload: 重新上傳技能

• GET api/v1/skills/{skillPk}/resources: 列出技能資源

• DELETE api/v1/skills/{skillPk}/resources/{id}: 刪除技能資源

• GET api/v1/skills/{skillPk}/resources/{id}/download: 下載技能資源

資料庫

• POST api/v1/sql-databases: 建立 SQL 資料庫連線

• GET api/v1/sql-databases: 列出 SQL 資料庫

• GET api/v1/sql-databases/{id}: 取得特定 SQL 資料庫

• PUT api/v1/sql-databases/{id}: 更新 SQL 資料庫

• PATCH api/v1/sql-databases/{id}: 部分更新 SQL 資料庫

• DELETE api/v1/sql-databases/{id}: 刪除 SQL 資料庫

• POST api/v1/sql-databases/{id}/test-connection: 測試資料庫連線

• POST api/v1/sql-databases/{id}/upload-files: 上傳檔案至資料庫

• POST api/v1/sql-databases/batch-delete: 批量刪除 SQL 資料庫

• GET api/v1/sql-databases/{sqlDatabasePk}/tables: 列出資料表

• POST api/v1/sql-databases/{sqlDatabasePk}/tables: 建立資料表

• GET api/v1/sql-databases/{sqlDatabasePk}/tables/{id}: 取得特定資料表

• PUT api/v1/sql-databases/{sqlDatabasePk}/tables/{id}: 更新資料表

• PATCH api/v1/sql-databases/{sqlDatabasePk}/tables/{id}: 部分更新資料表

• DELETE api/v1/sql-databases/{sqlDatabasePk}/tables/{id}: 刪除資料表

• POST api/v1/sql-databases/{sqlDatabasePk}/tables/batch-delete: 批量刪除資料表

• GET api/v1/sql-databases/{sqlDatabasePk}/tables/{tablePk}/columns: 列出資料欄位

• GET api/v1/sql-databases/{sqlDatabasePk}/tables/{tablePk}/columns/{id}: 取得特定資料欄位

• PUT api/v1/sql-databases/{sqlDatabasePk}/tables/{tablePk}/columns/{id}: 更新資料欄位

• PATCH api/v1/sql-databases/{sqlDatabasePk}/tables/{tablePk}/columns/{id}: 部分更新資料欄位

• POST api/v1/database-connection/test: 測試資料庫連線（通用）

• GET api/v1/database-examples: 列出資料庫連線字串範例

• GET api/v1/database-examples/{id}: 取得特定連線字串範例

• GET api/v1/chatbots/{chatbotPk}/databases: 列出 AI 助理的資料庫配置

• POST api/v1/chatbots/{chatbotPk}/databases: 新增 AI 助理的資料庫配置

• GET api/v1/chatbots/{chatbotPk}/databases/{id}: 取得特定資料庫配置

• PUT api/v1/chatbots/{chatbotPk}/databases/{id}: 更新資料庫配置

• PATCH api/v1/chatbots/{chatbotPk}/databases/{id}: 部分更新資料庫配置

• DELETE api/v1/chatbots/{chatbotPk}/databases/{id}: 刪除資料庫配置

認證要求

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

Authorization: Api-Key YOUR_API_KEY

使用說明

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

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

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

狀態碼說明

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