# 创雪 API（v1.0）— 给 agent 的速用说明

> 本文件与 https://snowfure.com/api/v1/manifest 同源，由 server/gen_api_spec.py 生成，勿手改。

## 基础信息
- base: https://snowfure.com/api
- 鉴权: 密钥三选一：查询串 ?key=… / 请求头 Authorization: Bearer … / X-API-Key: …
  - master（owner）: 主密钥（曾健本人，全权限，可颁发）
  - issued（apikey:<名字>）: 已颁发的 sk_… 密钥，按 scopes 限权
  - sso（<open_id>）: 飞书 SSO 令牌（?t=… 换来的会话令牌），只能看自己的数据
- 约定: UTF-8；POST 载荷 application/json；二进制（附件/语音）走 base64 字段

## 接口（80 个）
- POST https://snowfure.com/api/chat/stream — 流式对话（SSE 逐字返回）
    参数: model, messages
    curl -s -X POST 'https://snowfure.com/api/chat/stream?key=$KEY' -H 'Content-Type: application/json' -d '{"model": "glm-5.3", "messages": [{"role": "user", "content": "你好"}], "conversation_id": "", "recall": {"mode": "auto", "layers": ["essence", "summary"]}}'
- POST https://snowfure.com/api/chat/run — 一次性问答（非流式）
    参数: model, messages
    curl -s -X POST 'https://snowfure.com/api/chat/run?key=$KEY' -H 'Content-Type: application/json' -d '{"model": "glm-5.3", "messages": [{"role": "user", "content": "你好"}]}'
- GET https://snowfure.com/api/chat/conversations — 查 · 列出会话（按最近更新倒序，带 id/标题/模型/时间）
    参数: limit?
    curl -s 'https://snowfure.com/api/chat/conversations?key=$KEY&limit=…'
- GET https://snowfure.com/api/chat/conversation — 查 · 读一个会话的全部消息（含角色/内容/时间）
    参数: id
    curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'
- POST https://snowfure.com/api/chat/conversations — 增 · 新建空会话（返回新会话 id，可先起标题）
    参数: title?, model?
    curl -s -X POST 'https://snowfure.com/api/chat/conversations?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/rename — 改 · 重命名会话标题（最长 60 字）
    参数: id, title
    curl -s -X POST 'https://snowfure.com/api/chat/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- DELETE https://snowfure.com/api/chat/conversation — 删 · 删除会话（软删除，可在回收站恢复）
    参数: id
    curl -s 'https://snowfure.com/api/chat/conversation?key=$KEY&id=…'
- POST https://snowfure.com/api/chat/conversations/delete — 删 · 批量删除多个会话（软删除，可回滚）
    参数: ids（数组或逗号分隔，最多 200 个）
    curl -s -X POST 'https://snowfure.com/api/chat/conversations/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/insights — 洞察 · 从多个会话原文里提取事实/决策/方法/待办/金句（异步：返回 job_id）
    参数: ids（数组或逗号串）, prompt?（额外要求）
    curl -s -X POST 'https://snowfure.com/api/chat/insights?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/insights/result — 查 · 取洞察提取结果（轮询，模型要跑 40-90 秒）
    参数: job_id
    curl -s 'https://snowfure.com/api/chat/insights/result?key=$KEY&job_id=…'
- GET https://snowfure.com/api/chat/conversations/trash — 查 · 回收站：列出被删的会话（可恢复）
    curl -s 'https://snowfure.com/api/chat/conversations/trash?key=$KEY'
- POST https://snowfure.com/api/chat/conversations/restore — 改 · 从回收站恢复会话（回滚误删）
    参数: ids
    curl -s -X POST 'https://snowfure.com/api/chat/conversations/restore?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/conversations/purge — 彻底清除（仅回收站内，不可恢复）
    参数: ids
    curl -s -X POST 'https://snowfure.com/api/chat/conversations/purge?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/tasks — 增 · 新建提醒/推送任务（一次性 / 每天 / 每 N 分钟）
    参数: action=add, title, body, mode, at_time, repeat, channel
    curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/tasks — 删 · 删除任务
    参数: action=delete, id
    curl -s -X POST 'https://snowfure.com/api/chat/tasks?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/task/runs — 查 · 执行记录（每次投递的通道与回执）
    参数: limit?
    curl -s 'https://snowfure.com/api/chat/task/runs?key=$KEY&limit=…'
- GET https://snowfure.com/api/im/convos — 查 · 列曾健的任务（带编号 T1/T2…、进行中/已完成状态）
    参数: kind（固定 group，不用传）
    curl -s 'https://snowfure.com/api/im/convos?key=$KEY&kind（固定=…'
- POST https://snowfure.com/api/im/convo/done — 改 · 把任务标记为已完成（task 传编号如 T3，或会话 id）
    参数: task, done=1
    curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/convo/done — 改 · 重新打开已完成的任务（task 传编号如 T3，或会话 id）
    参数: task, done=0
    curl -s -X POST 'https://snowfure.com/api/im/convo/done?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/im/messages — 查 · 读一个任务里的消息记录（谁说了什么）
    参数: conv, before?
    curl -s 'https://snowfure.com/api/im/messages?key=$KEY&conv=…'
- POST https://snowfure.com/api/im/send — 增 · 往任务里发一条消息（@ 谁谁回）
    参数: conv, text
    curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/convo/rename — 改 · 重命名任务
    参数: id, title
    curl -s -X POST 'https://snowfure.com/api/im/convo/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/convo/delete — 删 · 删除任务
    参数: id
    curl -s -X POST 'https://snowfure.com/api/im/convo/delete?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/kb/web_search — 查 · 联网搜索（Bing）拿标题/网址/摘要
    参数: q, n?
    curl -s 'https://snowfure.com/api/kb/web_search?key=$KEY&q=…'
- POST https://snowfure.com/api/kb/import_url — 改 · 抓网页正文入库（自动跑流水线+图谱）
    参数: url, title?
    curl -s -X POST 'https://snowfure.com/api/kb/import_url?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/kb/web_pipeline — 改 · 联网搜索并抓前 N 篇自动入库（知识采集一条龙）
    参数: q, n?
    curl -s -X POST 'https://snowfure.com/api/kb/web_pipeline?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/kb/search — 查 · 知识库检索（上传入库的 PDF / Word / 表格 / 网页内容）
    参数: q, limit?
    curl -s 'https://snowfure.com/api/kb/search?key=$KEY&q=…'
- GET https://snowfure.com/api/kb/docs — 查 · 知识库文档清单
    curl -s 'https://snowfure.com/api/kb/docs?key=$KEY'
- GET https://snowfure.com/api/chat/arts — 汇总全部制品（图/文档）
    curl -s 'https://snowfure.com/api/chat/arts?key=$KEY'
- GET https://snowfure.com/api/chat/memories — 查 · 记忆列表（按 layer/domain/status/q 过滤；分层 SQL 下推，counts 与 items 严格同源）
    参数: status?, layer?, domain?, q?, page?, page_size?
    curl -s 'https://snowfure.com/api/chat/memories?key=$KEY&status=…'
- POST https://snowfure.com/api/chat/memories/ingest — 改 · 多模态记忆入库（PDF/图片/URL → 网盘 + 记忆双轨；skip_summary=true 时跳过 LLM 解读）
    参数: type, data|url, filename?, domain?, layer?, instruction?, skip_summary?, remark?
    curl -s -X POST 'https://snowfure.com/api/chat/memories/ingest?key=$KEY' -H 'Content-Type: application/json' -d '{"type": "url", "url": "https://mp.weixin.qq.com/s/xxx", "domain": "work", "layer": "summary"}'
- POST https://snowfure.com/api/chat/memories — 改 · 记忆批量操作（approve/reject/delete/layer 支持 ids[] 数组，单 id 兼容）
    参数: action, ids[]|id, layer?
    curl -s -X POST 'https://snowfure.com/api/chat/memories?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/memories — 查 · 同线索「前后说法不一」扫描（创雪 App 冲突提示的服务端口径）
    参数: action=conflicts
    curl -s -X POST 'https://snowfure.com/api/chat/memories?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/things — 事 · 创雪 App「做到」的五步流程（说清/方案/执行/交付/沉淀；add/list/update/delete）
    参数: action, id?, thread?, title?, said?, way?, by?, stage?, steps?
    curl -s -X POST 'https://snowfure.com/api/chat/things?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/ways — 做法 · 可复用配方 = 做法市场（内置种子 + 用户沉淀；list/add/update/use）
    参数: action, id?, q?, cat?, name?, steps?
    curl -s -X POST 'https://snowfure.com/api/chat/ways?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/drive/files — 查 · 开发者网盘文件清单（按 owner 隔离）
    参数: category?, q?, limit?, offset?, parent_id?
    curl -s 'https://snowfure.com/api/drive/files?key=$KEY&category=…'
- GET https://snowfure.com/api/drive/folders — 查 · 网盘文件夹树（移动/整理用）
    curl -s 'https://snowfure.com/api/drive/folders?key=$KEY'
- GET https://snowfure.com/api/drive/file — 查 · 网盘文件（raw=1 流式预览 / download=1 触发下载）
    参数: id, raw?, download?
    curl -s 'https://snowfure.com/api/drive/file?key=$KEY&id=…'
- POST https://snowfure.com/api/drive/upload_stream — 改 · 大文件流式上传（body=原始字节，Content-Length 必须；不进内存，支持 GB 级视频）
    参数: name, mime, parent_id?（query），body=二进制
    curl -s -X POST 'https://snowfure.com/api/drive/upload_stream?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/drive/move — 改 · 移动文件/文件夹（防环校验：不能移到自己的子孙里）
    参数: id, target_parent_id
    curl -s -X POST 'https://snowfure.com/api/drive/move?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/drive/rename — 改 · 重命名文件/文件夹
    参数: id, name
    curl -s -X POST 'https://snowfure.com/api/drive/rename?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/agents — 智能体清单
    curl -s 'https://snowfure.com/api/chat/agents?key=$KEY'
- GET https://snowfure.com/api/chat/sop — 读取 SOP 流程
    curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'
- GET https://snowfure.com/api/chat/onto/schema — 本体对象类型（W3C 类层次+属性）
    参数: scope?
    curl -s 'https://snowfure.com/api/chat/onto/schema?key=$KEY&scope=…'
- GET https://snowfure.com/api/chat/onto/graph — 本体对象子图（节点+关系）
    参数: type?, q?, hops?
    curl -s 'https://snowfure.com/api/chat/onto/graph?key=$KEY&type=…'
- GET https://snowfure.com/api/chat/onto/object — 本体单个对象详情（属性+链接）
    参数: uri
    curl -s 'https://snowfure.com/api/chat/onto/object?key=$KEY&uri=…'
- GET https://snowfure.com/api/chat/onto — 本体体检（文件/三元组/类/实例）
    参数: scope?
    curl -s 'https://snowfure.com/api/chat/onto?key=$KEY&scope=…'
- POST https://snowfure.com/api/chat/onto/query — 本体只读 SPARQL
    参数: sparql, scope?
    curl -s -X POST 'https://snowfure.com/api/chat/onto/query?key=$KEY' -H 'Content-Type: application/json' -d '{"sparql": "SELECT ?s ?p ?o WHERE {?s ?p ?o} LIMIT 5"}'
- POST https://snowfure.com/api/chat/onto/plan — 本体驱动：意图→SPARQL→事实→计划
    参数: intent, scope?
    curl -s -X POST 'https://snowfure.com/api/chat/onto/plan?key=$KEY' -H 'Content-Type: application/json' -d '{"intent": "重启微信上传网关"}'
- POST https://snowfure.com/api/chat/onto/run — 本体驱动：按事实下发智能体执行
    参数: peer, intent, facts, steps
    curl -s -X POST 'https://snowfure.com/api/chat/onto/run?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/sop — SOP 流程列表+当前全文
    curl -s 'https://snowfure.com/api/chat/sop?key=$KEY'
- POST https://snowfure.com/api/chat/sop — 保存/新建 SOP（action=save|new|delete|select）
    参数: action, id, name, text, auto
    curl -s -X POST 'https://snowfure.com/api/chat/sop?key=$KEY' -H 'Content-Type: application/json' -d '{"action": "save", "id": "s…", "name": "流程名", "text": "第一步：… ｜ 参与：… ｜ 交付：… ｜ 验收：总督"}'
- POST https://snowfure.com/api/chat/sop/ai — AI 对话优化 SOP / 创建缺失智能体
    参数: action=optimize|create, text, instruction, names
    curl -s -X POST 'https://snowfure.com/api/chat/sop/ai?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/drafts — 公众号草稿清单
    参数: q, status
    curl -s 'https://snowfure.com/api/chat/drafts?key=$KEY&q=…'
- GET https://snowfure.com/api/chat/draft — 读取草稿正文
    参数: id
    curl -s 'https://snowfure.com/api/chat/draft?key=$KEY&id=…'
- POST https://snowfure.com/api/chat/draft/ai — 草稿 AI（润色/扩写/缩写/语气/翻译/排版/标题/摘要/封面/大纲/重写/全文润色）
    参数: action, text, content, title, tone, style, instruction
    curl -s -X POST 'https://snowfure.com/api/chat/draft/ai?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/chat/draft/templates — 公众号 6 大场景模板
    curl -s 'https://snowfure.com/api/chat/draft/templates?key=$KEY'
- POST https://snowfure.com/api/chat/draft/snapshot — 草稿版本快照（save/list/restore/delete）
    参数: id, op, snapshot_id, note
    curl -s -X POST 'https://snowfure.com/api/chat/draft/snapshot?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/draft/kb_search — 草稿素材检索（记忆+网盘）
    参数: q
    curl -s -X POST 'https://snowfure.com/api/chat/draft/kb_search?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/draft/uploadimg — 草稿插图上传（落网盘+换微信永久URL，网关不可达降级站内链）
    参数: data(base64), mime, name
    curl -s -X POST 'https://snowfure.com/api/chat/draft/uploadimg?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/draft/mp_update — 本地改动回写微信草稿箱已有图文（draft/update）
    参数: id
    curl -s -X POST 'https://snowfure.com/api/chat/draft/mp_update?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/draft/mp_pull — 微信草稿箱拉回本地（无 media_id 列清单 / 有则导入全文）
    参数: media_id?
    curl -s -X POST 'https://snowfure.com/api/chat/draft/mp_pull?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/chat/upload — 附件上传 + 内容识别
    参数: name, data, mime
    curl -s -X POST 'https://snowfure.com/api/chat/upload?key=$KEY' -H 'Content-Type: application/json' -d '{"name": "a.png", "data": "<base64>", "mime": "image/png"}'
- POST https://snowfure.com/api/chat/asr — 语音转文字
    参数: data, mime
    curl -s -X POST 'https://snowfure.com/api/chat/asr?key=$KEY' -H 'Content-Type: application/json' -d '{"data": "<base64 音频>", "mime": "audio/wav"}'
- GET https://snowfure.com/api/im/convos — IM 会话列表
    curl -s 'https://snowfure.com/api/im/convos?key=$KEY'
- POST https://snowfure.com/api/im/send — 发 IM 消息
    参数: conv, text
    curl -s -X POST 'https://snowfure.com/api/im/send?key=$KEY' -H 'Content-Type: application/json' -d '{"conv": "<会话 id>", "text": "你好"}'
- GET https://snowfure.com/api/im/search — IM 消息全文检索（限自己所在会话）
    参数: q, conv?, limit?
    curl -s 'https://snowfure.com/api/im/search?key=$KEY&q=…'
- POST https://snowfure.com/api/im/typing — 「正在输入」信令（广播不落库）
    参数: conv
    curl -s -X POST 'https://snowfure.com/api/im/typing?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/read — 已读上报（广播回执）
    参数: conv, upto
    curl -s -X POST 'https://snowfure.com/api/im/read?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/msg/del — 撤回自己发的消息（软删+广播）
    参数: conv, seq
    curl -s -X POST 'https://snowfure.com/api/im/msg/del?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/im/people — IM 成员
    curl -s 'https://snowfure.com/api/im/people?key=$KEY'
- GET https://snowfure.com/api/im/contacts — IM 通讯录（人+智能体）
    curl -s 'https://snowfure.com/api/im/contacts?key=$KEY'
- GET https://snowfure.com/api/im/plugins — IM 插件注册表+在线状态
    curl -s 'https://snowfure.com/api/im/plugins?key=$KEY'
- POST https://snowfure.com/api/im/plugins/test — 测试插件连通
    参数: id
    curl -s -X POST 'https://snowfure.com/api/im/plugins/test?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/v1/keys — API 密钥清单
    curl -s 'https://snowfure.com/api/v1/keys?key=$KEY'
- GET https://snowfure.com/api/v1/apps — IM 应用清单（app_id，不含密钥）
    curl -s 'https://snowfure.com/api/v1/apps?key=$KEY'
- POST https://snowfure.com/api/v1/apps — 注册 IM 应用 → app_id/app_secret（harness 插件接入用）
    参数: name, ident, engine, glyph
    curl -s -X POST 'https://snowfure.com/api/v1/apps?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/v1/auth/app_access_token/internal — 应用换 token（仿飞书，2h 有效）
    参数: app_id, app_secret
    curl -s -X POST 'https://snowfure.com/api/v1/auth/app_access_token/internal?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- POST https://snowfure.com/api/im/ws/endpoint — 取 IM 长连接地址 + ClientConfig（仿飞书）
    参数: app_id, app_secret
    curl -s -X POST 'https://snowfure.com/api/im/ws/endpoint?key=$KEY' -H 'Content-Type: application/json' -d '{}'
- GET https://snowfure.com/api/im/ws/status — IM 长连接在线状态（排查用）
    curl -s 'https://snowfure.com/api/im/ws/status?key=$KEY'

## 流式对话（SSE）
- 接口: POST /api/chat/stream（text/event-stream）
- 帧格式: 每帧一行 `data: <json>`，帧间空行
  - {"snowfure":{"conversation_id":"…","recall":{…}}} ← 首帧：会话 id + 本轮召回统计（记忆/本体命中数）
  - {"choices":[{"delta":{"content":"字"}}]} ← 逐字增量：把 content 依次拼接
  - {"choices":[{"finish_reason":"stop"}],"usage":{…}} ← 收尾帧（可能带 usage 用量）
  - [DONE] ← 流结束，客户端收到即停止读取
  · 用 SSE 客户端逐行读 data:；遇 [DONE] 关闭连接
  · 首帧的 conversation_id 存下来，下次带上它就续上下文
  · 断线重连不会重复计费：重发同一 conversation_id 即可

## 错误码
- HTTP 401 UNAUTHORIZED — 缺密钥 / 密钥错 / 已吊销
- HTTP 403 FORBIDDEN — 身份没有该范围的数据权限
- HTTP 403 DEMO_DENIED — 演示身份调用了本地数据接口（只放开模型对话与网络数据）
- HTTP 404 NOT_FOUND — 对象不存在（会话/草稿/本体对象…）
- HTTP 400 BAD_ACTION — action 参数不认识
- HTTP 500 SAVE_FAIL / UPLOAD_FAIL / ASR_FAIL / MCP_FAIL / ARTS_FAIL — 对应模块内部错误，error 字段有原因

## 接入步骤
- 1) 拿密钥：控制台 https://snowfure.com/admin/#/api/keys 签发 sk_…（或用已有主密钥）
- 2) 自检：GET /api/v1/whoami?key=$KEY 确认身份
- 3) 拿模型/智能体：GET /api/chat/agents（智能体清单）；模型名直接用 deepseek-flash / glm-5.3-flash 等网关型号
- 4) 对话：POST /api/chat/stream（SSE）或 POST /api/chat/run（一次拿完）
- 5) 产物/资料：GET /api/chat/arts、/api/chat/conversations、/api/chat/drafts
- 6) 本体事实：GET /api/chat/onto、/api/chat/onto/graph、POST /api/chat/onto/query（SPARQL）
- 7) 语音/文件：POST /api/chat/asr、/api/chat/upload
- 8) 别把密钥写进代码：从环境变量读，例 export KEY=sk_…

## 人看的页面
- 控制台: https://snowfure.com/admin/#/api/api