会话 API

会话有两套路由：

• 用户会话（agents 路由器）：挂载在 /api/v1/agents 下，只作用于当前用户自己的会话，支持查询、重命名、删除会话与删除单条消息。
• 平台会话（conversations 路由器）：挂载在 /api/v1/conversations 下，面向团队/管理视角，支持分页检索团队内会话、查看详情、单条与批量删除，以及会话统计。

两套路由都需要 conversation:read（写操作为 conversation:delete）。

端点总览

用户会话端点

用户端点全部以 Conversation.user 为范围：访问他人的会话一律按「不存在」处理（404，错误码 6210）。每个端点的参数、响应与错误详见 Agent API 的 Agent 会话。

平台会话端点

平台路由器面向团队/管理视角，是管理后台「会话管理」页面的数据源。

分页检索会话

GET /api/v1/conversations

结果按 updated_at 降序返回 PageData[ConversationListOut]。列表项除会话字段外还包含管理视图专用的 user_id、user_name，以及冗余的 agent_name、agent_icon。

获取会话详情

GET /api/v1/conversations/{conversation_id}

返回 ConversationWithMessages：会话字段 + messages（可见消息，逐条带 version_count），并额外带 user_id、user_name。与用户端点不同，平台详情允许具备仪表盘访问权限的管理员读取团队内他人的会话。

删除会话

DELETE /api/v1/conversations/{conversation_id}

curl -X DELETE "https://your-domain.com/api/v1/conversations/conv-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

批量删除会话

DELETE /api/v1/conversations?ids=conv-123&ids=conv-456

ids 是必填的重复查询参数（list[UUID]），不是 JSON 请求体。批量删除不会回滚单条失败：只要至少一个目标存在就执行删除，只有全部目标都不存在时才返回 404（6210）。删除同样是永久的，建议先按时间、团队、用户与 Agent 筛选确认范围。

访问范围

平台端点的可见范围由「可访问 Agent + 仪表盘权限」共同决定：

非超级管理员在指定 team_id 时会先校验团队成员身份；无可访问 Agent 时列表返回空结果（不报错）。

会话统计

两条统计路由都以「可访问 Agent」为底座，并叠加 own_only 与仪表盘权限：

• 不传 team_id 时，范围是调用者所在团队的全部 Agent（超级管理员为全部 Agent）。
• 传入 team_id 时，范围限定为该团队的 Agent，并校验团队成员身份。
• 具备仪表盘访问权限（超级管理员，或指定团队的所有者/管理员）时看到范围内全部会话；普通成员/访客只看到自己的会话。
• own_only=true 会把任何调用者都限制为自己的会话。

会话统计概览

GET /api/v1/conversations/stats

{
  "code": 0,
  "data": {
    "total_conversations": 1284,
    "total_messages": 18237,
    "conversations_by_agent": [
      {
        "agent_id": "1c2f1a2e-0f4e-4a8f-9d4a-2b0d7b3dcb6d",
        "agent_name": "Support Assistant",
        "agent_icon": "life-buoy",
        "count": 742
      }
    ]
  },
  "msg": "success"
}

conversations_by_agent 最多返回会话数最多的 10 个 Agent，按数量降序。若某 Agent 记录已无法解析，agent_name 回退为本地化的「unknown」文案，agent_icon 为 null。

会话趋势

GET /api/v1/conversations/stats/trends?period=30d

{
  "code": 0,
  "data": {
    "period": "7d",
    "data": [
      {
        "date": "09/20",
        "conversations": 34,
        "messages": 512,
        "tokens": 187340,
        "users": {}
      }
    ]
  },
  "msg": "success"
}

消息版本

消息可有多个版本，响应包含 version_number、is_active、父消息/分支关系与 version_count。编辑或重新生成会创建分支；切换版本只改变活动版本，且会停用所选版本之后的版本（它们基于旧分支）。详见 Agent 聊天 API 的消息版本。

错误码

相关文档

• Agent 聊天 API — 发送消息、流式响应与持久运行
• Agent API — Agent 管理、Agent 会话端点与 Agent 统计
• SSE 流式事件 — 运行事件与断点续连