REST 端点

所有端点 base URL https://api.hashee.ai，认证除标 Public 外都用 Authorization: Bearer {token}。详见 认证。

本页是端点目录 + 字段速查。具体业务流程在对应章节展开（如 grants 走 SDK Data Grants，文件走 文件上传）。

认证

方法	路径	认证	说明
POST	/auth/register	Public	4 步注册流程
POST	/auth/login	Public	密码登录
POST	/auth/login-code	Public	验证码登录
POST	/auth/send-code	Public	发验证码（scene: register/login/reset）
POST	/auth/refresh	Cookie	刷新 access_token
POST	/auth/logout	JWT	注销当前 session
POST	/auth/reset-password	Public	重置账户密码
POST	/auth/change-password	JWT	修改账户密码
POST	/auth/change-protection-password	JWT	修改保护密码（影响 E2EE 备份）
GET	/auth/me	JWT	当前用户基础信息
POST	/auth/passkey/begin	Public	Passkey 登录开始
POST	/auth/passkey/complete	Public	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	当前用户完整 profile
PATCH	/users/me	JWT	更新 profile（display_name / avatar / bio / locale）
GET	/users/:id	JWT	通过 ID 取用户公开信息
GET	/users/search?q=...	JWT	搜用户（按 display_name / handle）
DELETE	/users/me	JWT	销户（GDPR right to erasure）
PATCH	/users/contacts/:id	JWT	给联系人设备注名

E2EE 密钥

方法	路径	认证	说明
POST	/keys/backup	JWT	上传 E2EE 私钥的加密备份（仅密文）
GET	/keys/backup	JWT	拉自己加密备份（明文恢复在客户端）
PUT	/keys/backup	JWT	更新备份
GET	/keys/users/:id/devices	JWT	拉用户所有设备的公钥（路由消息用）
GET	/keys/agents/:id	JWT	拉 Agent 公钥（含 X25519 + Ed25519）
GET	/keys/groups/:id	JWT	拉 group key 的 wraps
POST	/keys/groups/:id/rotate	JWT	触发 group key 轮换
POST	/keys/rotation/request	JWT	申请 H2H ratchet 重置
POST	/keys/rotation/confirm	JWT	确认 H2H ratchet 重置
POST	/agents/:id/keys/register	Agent	Agent 注册自己的 X25519 + Ed25519 公钥

对话

方法	路径	认证	说明
GET	/conversations	JWT	列活跃会话（按 last_activity 倒序）
PATCH	/conversations/:id	JWT	改设置（mute / pin / archive）
DELETE	/conversations/:id	JWT	隐藏会话（不删消息）
POST	/conversations/:id/read	JWT	标记已读到 seq
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	Human 发消息
POST	/messages/:id/recall	JWT	撤回（2 分钟内）
POST	/messages/:id/reactions	JWT	加 / 取消 reaction
GET	/messages/:id/reactions	JWT	拉 reaction 聚合
POST	/messages/forward	JWT	转发（最多 10 个目标）
PATCH	/messages/:id/artifact	Agent	更新已发 artifact（带 revision）

群组

方法	路径	认证	说明
POST	/groups	JWT	创建群
GET	/groups/:id	JWT	群详情
PATCH	/groups/:id	JWT	改群设置（名称 / 头像 / dm policy）
DELETE	/groups/:id	JWT	解散群
GET	/groups/:id/members	JWT	列成员
POST	/groups/:id/members	JWT	加成员
DELETE	/groups/:gid/members/:mid	JWT	踢成员 → 触发 group key 轮换
PATCH	/groups/:gid/members/:mid	JWT	改成员角色 (owner/admin/member)
PATCH	/groups/:gid/members/me	JWT	改自己在群的资料（备注名等）
POST	/groups/:gid/leave	JWT	自己退群 → 触发 group key 轮换
POST	/groups/:id/transfer	JWT	owner 转让
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 管理（owner 视角）

方法	路径	认证	说明
POST	/agents	JWT	创建 Agent（V1 通过 System Agent 引导）
GET	/agents	JWT	列我的 Agent
GET	/agents/:id	JWT	Agent 详情
PATCH	/agents/:id	JWT	改 Agent profile / capability_manifest
DELETE	/agents/:id	JWT	删 Agent（cascade 撤销所有 H2A）
GET	/agents/check-id?handle=...	JWT	检查自定义 handle 可用
GET	/agents/:id/token	JWT	取 Agent 当前 token hash 信息
POST	/agents/:id/token/regenerate	JWT	重新生成 token
DELETE	/agents/:id/token	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	列待批准 user 请求（dmPolicy=approved 时）
POST	/agents/:id/requests/:rid/approve	JWT	批准
POST	/agents/:id/users/:uid/suspend	JWT	暂停某 user 的访问
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/messages	Agent	发消息（payload 里带 conversation_id）
POST	/agents/:id/typing	Agent	typing 指示
GET	/agents/:id/messages/poll?since=...	Agent	长轮询新消息
GET	/agents/:id/conversations	Agent	列 Agent 参与的 conversation
GET	/agents/:id/conversations/:cid/messages	Agent	拉 conv 历史
POST	/agents/:id/files	Agent	申请文件预签名 URL
PUT	/agents/:id/files/:uploadId/upload	Agent	上传文件
POST	/files/confirm	Agent	确认上传完成（含 SHA-256）
POST	/agents/:id/connection/recover	Agent	Webhook 模式 unreachable 恢复
GET	/agents/:id/delivery-logs?limit=50	Agent	拉最近 30 天 webhook delivery 日志
DELETE	/agents/:id/grants/:gid	Agent	Agent 主动归还 grant

数据授权 (Grants)

方法	路径	认证	说明
POST	/agents/:id/grants/request	Agent	Agent 申请 grant（生成 artifact approval）
GET	/users/me/grants	JWT	用户视角：列已授权
DELETE	/users/me/grants/:gid	JWT	用户撤销 grant
GET	/agents/:id/grants/:gid/log	Agent	取自己的访问日志（自查）

详见 Data Grants。

文件

方法	路径	认证	说明
POST	/files/presign	JWT	申请预签名上传 URL
PUT	/files/:upload_id/upload	JWT	PUT 二进制
POST	/files/confirm	JWT	用 SHA-256 确认

详见 文件上传。

其他

方法	路径	认证	说明
GET	/health	Public	健康检查 ({"status":"ok"})
GET	/search?q=...	JWT	全局搜（用户、Agent、群、消息）
POST	/reports	JWT	举报 Agent / 用户 / 群
POST	/share/friend	JWT	创建好友分享链接
POST	/share/agent	JWT	创建 Agent 分享链接
POST	/share/group	JWT	创建群分享链接
GET	/share/*	Public	解析分享链接（不显示密文）

下一步

• WebSocket 事件
• Webhook 协议
• 错误码
• 速率限制与重试