服务 API — 集成平台

整个 Web 界面都构建在 HTTP + SSE API 之上，你可以从自己的系统直接调用。基地址：https://<你的域名>/api/v1。

1. 认证（JWT）

curl -X POST $BASE/api/v1/auth/login -H 'content-type: application/json' \
  -d '{"email":"dev@acme.com","password":"…"}'   # → { access_token, refresh_token }

之后每次调用携带 Authorization: Bearer <access_token>。

1b. 个人 API 密钥（推荐用于集成）

无需使用密码，可创建 API 密钥：设置 → 🔑 API 密钥 → “新建密钥”。密钥（sk_live_...）仅显示一次——请立即复制。最多 20 个有效密钥，可随时在同一页面撤销。

TOKEN=$(curl -s -X POST $BASE/api/v1/auth/token -H "X-API-Key: sk_live_..." | jq -r .access_token)
curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOKEN" ...

服务器只存储密钥的哈希值。撤销密钥会立即阻止新的兑换；已签发的令牌会在 15 分钟内过期。用量计入您的正常余额。

2. 与智能体对话

curl -X POST $BASE/api/v1/chat -H "Authorization: Bearer $TOK" -H 'content-type: application/json' -d '{
  "message": "审查这份合同并列出风险",
  "app_name": "contract_review_dz",
  "attachments": ["<upload_id>"],
  "kb_ids": ["<kb_id>"]
}'
# → { "run_id", "session_id", "cursor" }

app_name — 目标智能体：目录中的任意智能体，或自定义智能体 custom_<id>。
kb_ids — 让智能体基于你的知识库回答：对话期间在这些工作区上做 RAG。
attachments — 通过 POST /api/v1/uploads 上传的文件 id。

3. 流式获取回答（SSE）

curl -N $BASE/api/v1/runs/$RUN_ID/events -H "Authorization: Bearer $TOK"

主要事件：token（文本片段）、tool_call/tool_result（工具调用）、plan/plan_step（执行计划与进度）、document_*（流式撰写的文档）、chart（交互图表）、file/artifact（产出文件 → GET /api/v1/artifacts/{id}）、usage/done/error。断线后可用 Last-Event-ID 续传。

4. 直接查询工作区（知识库）

curl -N -X POST $BASE/api/v1/kb/query/stream -H "Authorization: Bearer $TOK" \
 -H 'content-type: application/json' -d '{
  "kb_id":"<kb_id>", "q":"有哪些解约条款？", "enhance": true, "mode": "auto", "cite": true }'

模式：auto · quick · full · deep · graph_local · graph_global，agent: true 分解，[N] 引用，图片提取，按次成本。详见知识库。

5. 可嵌入组件（在你的网站上的公开聊天机器人）

在集成 → Widget 创建组件后粘贴：

<script src="https://<域名>/embed.js" data-widget="<widget_key>" defer></script>

6. 公开分享

共享知识库：POST /api/v1/kb/{id}/share → /shared-kb/<slug> 链接可公开查询（计费给所有者）。
文档 / 项目：类似的分享链接。