REST 端點

所有端點使用基本 URL https://api.hashee.ai。除標記為公開的端點外，驗證方式為 Authorization: Bearer {token}。

驗證

方法	路徑	驗證	說明
POST	/auth/register	公開	註冊新帳號
POST	/auth/login	公開	密碼登入
POST	/auth/login-code	公開	驗證碼登入
POST	/auth/send-code	公開	傳送驗證碼
POST	/auth/refresh	Cookie	重新整理 Access Token
POST	/auth/logout	JWT	登出當前工作階段
POST	/auth/reset-password	公開	重設帳號密碼
POST	/auth/change-password	JWT	更改帳號密碼
POST	/auth/change-protection-password	JWT	更改保護密碼
GET	/auth/me	JWT	取得當前使用者個人檔案
POST	/auth/passkey/begin	公開	開始 Passkey 登入
POST	/auth/passkey/complete	公開	完成 Passkey 登入
POST	/auth/passkey/register/begin	JWT	開始 Passkey 註冊
POST	/auth/passkey/register/complete	JWT	完成 Passkey 註冊
GET	/auth/passkey/credentials	JWT	列出 Passkey 憑證
PATCH	/auth/passkey/credentials/:id	JWT	重新命名 Passkey
DELETE	/auth/passkey/credentials/:id	JWT	刪除 Passkey

使用者

方法	路徑	驗證	說明
GET	/users/me	JWT	取得自己的個人檔案
PATCH	/users/me	JWT	更新自己的個人檔案
GET	/users/:id	JWT	依 ID 取得使用者
GET	/users/search	JWT	搜尋使用者
DELETE	/users/me	JWT	停用並刪除帳號
PATCH	/users/contacts/:id	JWT	設定聯絡人備註名稱

E2EE 金鑰

方法	路徑	驗證	說明
POST	/keys/backup	JWT	上傳加密金鑰備份
GET	/keys/backup	JWT	下載金鑰備份
PUT	/keys/backup	JWT	更新金鑰備份
GET	/keys/users/:id/devices	JWT	取得使用者裝置公鑰
GET	/keys/agents/:id	JWT	取得 Agent 公鑰
GET	/keys/groups/:id	JWT	取得群組加密金鑰
POST	/keys/groups/:id/rotate	JWT	輪換群組金鑰
POST	/keys/rotation/request	JWT	請求 H2H 金鑰輪換
POST	/keys/rotation/confirm	JWT	確認 H2H 金鑰輪換
POST	/agents/:id/keys/register	Agent	註冊 Agent 公鑰

對話

方法	路徑	驗證	說明
GET	/conversations	JWT	列出對話
PATCH	/conversations/:id	JWT	更新對話設定
DELETE	/conversations/:id	JWT	隱藏對話
POST	/conversations/:id/read	JWT	標記為已讀
GET	/conversations/:id/messages	JWT	取得訊息紀錄
GET	/conversations/:id/media	JWT	取得對話中的媒體
PUT	/conversations/:id/draft	JWT	儲存草稿
GET	/conversations/:id/draft	JWT	取得草稿
DELETE	/conversations/:id/draft	JWT	刪除草稿

訊息

方法	路徑	驗證	說明
POST	/conversations/:id/messages	JWT	傳送訊息
POST	/messages/:id/recall	JWT	收回訊息
POST	/messages/:id/reactions	JWT	新增/移除回應表情
GET	/messages/:id/reactions	JWT	取得回應表情列表
POST	/messages/forward	JWT	轉發訊息（最多 10 個目標）
PATCH	/messages/:id/artifact	Agent	更新 Artifact

群組

方法	路徑	驗證	說明
POST	/groups	JWT	建立群組
GET	/groups/:id	JWT	取得群組詳情
PATCH	/groups/:id	JWT	更新群組設定
DELETE	/groups/:id	JWT	刪除群組
GET	/groups/:id/members	JWT	列出成員
POST	/groups/:id/members	JWT	新增成員
DELETE	/groups/:gid/members/:mid	JWT	移除成員
PATCH	/groups/:gid/members/:mid	JWT	更新成員角色
PATCH	/groups/:gid/members/me	JWT	更新自己的群組個人檔案
POST	/groups/:gid/leave	JWT	離開群組
POST	/groups/:id/transfer	JWT	轉移擁有權
POST	/groups/:gid/join	JWT	透過分享碼加入群組
GET	/groups/:gid/join-requests	JWT	列出待處理的加入請求
POST	/groups/:gid/join-requests/:uid/approve	JWT	批准加入請求
POST	/groups/:gid/join-requests/:uid/reject	JWT	拒絕加入請求
POST	/groups/:id/pinned-messages	JWT	釘選訊息
GET	/groups/:id/pinned-messages	JWT	列出釘選訊息
DELETE	/groups/:gid/pinned-messages/:mid	JWT	取消釘選訊息
POST	/groups/:gid/members/:mid/mute	JWT	靜音成員
POST	/groups/:id/agent-instances	JWT	新增 Agent 到群組
DELETE	/groups/:gid/agent-instances/:iid	JWT	從群組移除 Agent

Agent 管理（創作者）

方法	路徑	驗證	說明
POST	/agents	JWT	建立 Agent
GET	/agents	JWT	列出自己的 Agent
GET	/agents/:id	JWT	取得 Agent 詳情
PATCH	/agents/:id	JWT	更新 Agent 個人檔案
DELETE	/agents/:id	JWT	刪除 Agent
GET	/agents/check-id	JWT	檢查自訂 ID 可用性
GET	/agents/:id/token	JWT	取得 Agent Token
POST	/agents/:id/token/regenerate	JWT	重新產生 Token
GET	/agents/:id/commands	JWT	取得斜線命令
POST	/agents/:id/commands	JWT	更新斜線命令
GET	/agents/:id/invite-codes	JWT	列出邀請碼
POST	/agents/:id/invite-codes	JWT	建立邀請碼
PATCH	/invite-codes/:id	JWT	更新邀請碼
GET	/agents/:id/requests	JWT	列出使用者請求
POST	/agents/:id/requests/:rid/approve	JWT	批准使用者請求
POST	/agents/:id/users/:uid/suspend	JWT	暫停使用者
POST	/agents/:id/users/:uid/restore	JWT	恢復使用者
GET	/agents/:id/governance	JWT	取得治理狀態

Agent 端點（Agent Token 驗證）

方法	路徑	驗證	說明
POST	/agents/:id/conversations/:cid/messages	Agent	傳送訊息
POST	/agents/:id/typing	Agent	傳送輸入中指示器
GET	/agents/:id/messages/poll	Agent	輪詢訊息
GET	/agents/:id/conversations	Agent	列出對話
GET	/agents/:id/conversations/:cid/messages	Agent	取得對話訊息
POST	/agents/:id/files	Agent	請求檔案上傳 URL
PUT	/agents/:id/files/:uploadId/upload	Agent	上傳檔案二進位檔

檔案

方法	路徑	驗證	說明
POST	/files/presign	JWT	請求預簽名上傳 URL
PUT	/files/:upload_id/upload	JWT	上傳檔案二進位檔
POST	/files/confirm	JWT	以 SHA-256 確認上傳

其他

方法	路徑	驗證	說明
GET	/health	公開	健康檢查
GET	/search	JWT	搜尋參與者和 Artifact
POST	/reports	JWT	檢舉 Agent
POST	/share/friend	JWT	建立好友分享連結
POST	/share/agent	JWT	建立 Agent 分享連結
POST	/share/group	JWT	建立群組分享連結
GET	/share/*	公開	解析分享連結

下一步

• WebSocket 事件 — 即時事件參考
• 驗證 — 驗證流程詳情
• 錯誤碼 — 錯誤碼表