{"openapi":"3.1.0","info":{"title":"超级大脑 · 开放平台 API","version":"1.0.0","description":"《超级大脑》知识引擎对外开放接口（网关前缀 `/openapi/v1`）。\n\n接入方式：① `app_key + app_secret` 换取 `access_token`；② 以 `Authorization: Bearer <access_token>` 调用数据面接口。\n\n调用受六道治理约束：鉴权 → 接口白名单 → 空间隔离 → 限流 → 脱敏 → 审计。所有响应（含错误响应）均携带 `X-Request-Id` 响应头（形如 `req_1a2b3c4d5e6f`），报障 / 排查时请携带该值（Q-04）。"},"servers":[{"url":"/","description":"同源部署"}],"tags":[{"name":"连通性","description":"无需鉴权的连通性自检"},{"name":"鉴权","description":"凭证换取访问令牌"},{"name":"数据面","description":"知识检索与问答（Bearer 令牌）"}],"security":[],"paths":{"/openapi/v1/health":{"get":{"tags":["连通性"],"summary":"连通性自检","description":"无需任何令牌。返回 `{\"status\":\"ok\"}`，不泄漏版本、地址等内部信息。","security":[],"responses":{"200":{"description":"服务正常","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"}},"required":["status"]},"example":{"status":"ok"}}}}}}},"/openapi/v1/auth/token":{"post":{"tags":["鉴权"],"summary":"换取访问令牌","description":"以 `app_key + app_secret` 换取 `access_token`（Bearer 携带，默认 2 小时）与 `refresh_token`（7 天，不轮换）。\n\n凭证错误统一返回 401「凭证无效」（不区分原因，防枚举）；应用停用返回 403；本端点接入 IP 级限流（超限 429 + Retry-After）。","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_key":{"type":"string","description":"应用 Key"},"app_secret":{"type":"string","description":"应用 Secret"}},"required":["app_key","app_secret"]},"example":{"app_key":"ak_xxx","app_secret":"sk_xxx"}}}},"responses":{"200":{"description":"签发成功","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","const":"Bearer"},"expires_in":{"type":"integer","description":"access_token 有效期（秒，默认 7200）"},"refresh_token":{"type":"string","description":"刷新令牌（仅此一次明文可见；7 天内有效）"},"refresh_expires_in":{"type":"integer","description":"refresh_token 有效期（秒，默认 604800）"}},"required":["access_token","token_type","expires_in"]},"example":{"access_token":"eyJhbGciOi…","token_type":"Bearer","expires_in":7200,"refresh_token":"a1b2…","refresh_expires_in":604800}}}},"401":{"description":"凭证无效","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"凭证无效"}}}},"403":{"description":"应用已停用","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"应用已停用"}}}},"429":{"description":"调用频率超限（IP 级限流；响应体 code=42902）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用频率超限","code":42902}}}}}}},"/openapi/v1/auth/refresh":{"post":{"tags":["鉴权"],"summary":"刷新访问令牌","description":"以 `refresh_token` 换取新的 `access_token`（refresh 本身**不轮换**，仍使用原值）。\n\nrefresh_token 失效（过期 / 已吊销 / 不匹配）统一返回 401「凭证无效」（防枚举）；新签发的 access_token 携带新 jti 并登记，可被管理端单独吊销。","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","description":"换取访问令牌时下发的 refresh_token"}},"required":["refresh_token"]},"example":{"refresh_token":"a1b2…"}}}},"responses":{"200":{"description":"刷新成功（返回新 access_token；refresh_token 不轮换）","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"新签发的访问令牌（新 jti）"},"token_type":{"type":"string","const":"Bearer"},"expires_in":{"type":"integer","description":"新 access_token 有效期（秒）"},"refresh_expires_in":{"type":"integer","description":"原 refresh_token 的剩余有效期（秒）"}},"required":["access_token","token_type","expires_in","refresh_expires_in"]},"example":{"access_token":"eyJhbGciOi…","token_type":"Bearer","expires_in":7200,"refresh_expires_in":604000}}}},"401":{"description":"refresh_token 无效 / 已过期 / 已吊销（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"凭证无效"}}}},"403":{"description":"应用已停用","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"应用已停用"}}}},"503":{"description":"令牌刷新服务暂不可用（登记表迁移未完成时的降级态）"}}}},"/openapi/v1/retrieve":{"post":{"tags":["数据面"],"summary":"知识检索（只读）","description":"在应用**授权范围内**的知识库中检索知识片段（授权范围由开放平台「设置」维护，范围外内容零返回）；空结果返回 200 + `results: []` + `notice`（合法业务态，非错误）。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":2000,"description":"检索语句"},"top_k":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"返回条数（默认 5；上限 20，超出自动收敛为上限并在响应回显实际值，不报错）"},"kb_ids":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"本次调用限定检索的知识库 ID 列表（可选，≤20 个；须在应用授权范围内，越权返回 403「该知识库不在应用的授权范围内」；不传则用应用级授权范围）"},"metadata_filters":{"type":"object","description":"元数据过滤（可选，≤10 键，值为字符串或字符串数组；引擎暂不支持，已预留：参数可传，但当前不会改变检索结果）"},"rerank":{"type":"boolean","default":false,"description":"重排开关（引擎暂不支持，已预留，当前不生效）"},"score_threshold":{"type":"number","minimum":0,"maximum":1,"description":"分数阈值（0~1；引擎暂不支持，已预留，当前不生效）"}},"required":["query"]},"example":{"query":"报销流程","top_k":5}}}},"responses":{"200":{"description":"检索结果（含空结果）","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"top_k":{"type":"integer","description":"实际生效条数"},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"片段标题（文档名 / 章节路径）"},"content":{"type":"string","description":"片段内容（已按应用配置脱敏）"},"source":{"type":"string","description":"来源文档标识（引擎文档 ID，兼容旧字段）"},"doc_id":{"type":"string","description":"平台文档 ID（可直接用于 GET /openapi/v1/documents/{doc_id}/download）"},"url":{"type":"string","description":"原文链接：URL 摄入=原始公网地址；上传文件=平台下载端点（需带同一 Bearer 令牌）"},"source_url":{"type":"string","description":"原始来源 URL（仅 URL 摄入且为公网地址时出现）"},"score":{"type":["number","null"],"description":"相关度分数（引擎相对相似度，跨引擎/跨库不可比；有值才透传）"},"chunk_id":{"type":"string","description":"命中的知识片段 ID（可选，仅部分后端提供）"},"positions":{"type":"array","items":{"type":"string"},"description":"片段在原文中的页码/位置定位（可选，仅部分后端提供）"}},"required":["title","content","source"],"title":"RetrieveResult"}},"latency_ms":{"type":"integer"},"notice":{"type":"string","description":"空结果提示（仅空结果时出现）"}},"required":["query","top_k","results","latency_ms"]},"example":{"query":"报销流程","top_k":5,"results":[{"title":"费用报销制度.docx","content":"…报销标准与流程…","source":"a1b2c3_external-download","score":0.87}],"latency_ms":356}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"凭证无效"}}}},"403":{"description":"接口未授权 / 应用停用 / 未授权任何空间 / 密钥级权限不足（该密钥 scope 不含本接口）/ 请求 kb_ids 越权（该知识库不在应用的授权范围内）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"该知识库不在应用的授权范围内"}}}},"422":{"description":"参数校验失败（如 query 为空或超长；kb_ids 非 UUID/超 20 个）"},"429":{"description":"调用频率超限（code=42902，含 Retry-After）/ 配额用尽（code=42901，另带 X-Quota-* 响应头）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用配额已用尽","code":42901}}}},"502":{"description":"知识引擎暂时不可用","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"知识引擎暂时不可用"}}}},"503":{"description":"知识引擎熔断保护已开启（重试仍失败；Retry-After 为熔断窗口剩余秒数）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"引擎服务暂时不可用，已开启熔断保护，请稍后重试"}}}},"504":{"description":"知识引擎响应超时","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"知识引擎响应超时"}}}}}}},"/openapi/v1/retrieve/batch":{"post":{"tags":["数据面"],"summary":"知识检索（批量，P-23）","description":"单次提交多条检索（items ≤50）。逐条并发执行，部分失败逐条标注（HTTP 恒 200）；配额按**实际条数**预留（N 条计 N 次），限流按 1 次调用；本路径需应用显式授权（存量应用默认未授权本路径 → 403「该接口未授权」）。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","minItems":1,"maxItems":50,"description":"检索条目列表（1~50 条；超出 422 整体拒绝）","items":{"type":"object","properties":{"query":{"type":"string","maxLength":2000},"top_k":{"type":"integer","minimum":1,"maximum":20,"default":5},"kb_ids":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"本条检索限定知识库（可选；越权 403 仅在该条 error 回显）"}},"required":["query"]}}},"required":["items"]},"example":{"items":[{"query":"报销流程","top_k":5},{"query":"请假制度"}]}}}},"responses":{"200":{"description":"批量检索结果（部分失败逐条标注；HTTP 恒 200）","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","description":"逐条结果（与请求顺序一致）","items":{"type":"object","properties":{"ok":{"type":"boolean"},"query":{"type":"string"},"top_k":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"片段标题（文档名 / 章节路径）"},"content":{"type":"string","description":"片段内容（已按应用配置脱敏）"},"source":{"type":"string","description":"来源文档标识（引擎文档 ID，兼容旧字段）"},"doc_id":{"type":"string","description":"平台文档 ID（可直接用于 GET /openapi/v1/documents/{doc_id}/download）"},"url":{"type":"string","description":"原文链接：URL 摄入=原始公网地址；上传文件=平台下载端点（需带同一 Bearer 令牌）"},"source_url":{"type":"string","description":"原始来源 URL（仅 URL 摄入且为公网地址时出现）"},"score":{"type":["number","null"],"description":"相关度分数（引擎相对相似度，跨引擎/跨库不可比；有值才透传）"},"chunk_id":{"type":"string","description":"命中的知识片段 ID（可选，仅部分后端提供）"},"positions":{"type":"array","items":{"type":"string"},"description":"片段在原文中的页码/位置定位（可选，仅部分后端提供）"}},"required":["title","content","source"],"title":"RetrieveResult"}},"error":{"type":"object","description":"该条失败原因 {status, detail}（仅失败条出现）"},"latency_ms":{"type":"integer"},"notice":{"type":"string"}}}},"latency_ms":{"type":"integer","description":"整批耗时"}}}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"凭证无效"}}}},"403":{"description":"接口未授权 / 应用停用 / 未授权任何空间 / 密钥级权限不足","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"422":{"description":"items 为空/超 50 / 条目校验失败（整体拒绝）"},"429":{"description":"调用频率超限（code=42902，含 Retry-After）/ 配额用尽（code=42901，另带 X-Quota-* 响应头）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用配额已用尽","code":42901}}}},"502":{"description":"知识引擎暂时不可用","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"504":{"description":"知识引擎响应超时","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}}}}},"/openapi/v1/ask":{"post":{"tags":["数据面"],"summary":"知识问答（同步 JSON / SSE 流式）","description":"在应用授权空间内提问。默认（stream=false）服务端内部消费流式 RAG 引擎后**聚合为单次 JSON**，降低第三方接入成本；传 `stream=true` 时**直通 SSE**（text/event-stream），逐 token 输出并逐帧脱敏，首字延迟接近引擎生成速度。支持多轮会话：传 `conversation_id`（服务端保留最近 20 轮历史）或直接携带 `history`。请求级生成参数（temperature/top_p/max_tokens）与应用级生成参数（temperature/top_p/max_answer_len）已预留：当前引擎不支持按请求/应用指定，平台在引擎支持前不消费这些值（请求级参数超安全区间自动收敛，合并结果仅记录）。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":2000,"description":"问题文本"},"top_k":{"type":"integer","minimum":1,"default":8,"description":"检索条数（默认 8；上限 20，超出自动收敛为上限，不报错）"},"stream":{"type":"boolean","default":false,"description":"true 时返回 SSE 流式（text/event-stream）；默认 false = 同步 JSON"},"conversation_id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]{1,64}$","description":"会话 ID（应用内唯一）；服务端按 (应用, 会话) 保存最近 20 轮历史，再次携带即续接多轮对话"},"history":{"type":"array","maxItems":20,"description":"本轮之前的对话历史（每项 {role:'user'|'assistant', content}）；与 conversation_id 同时传时以本字段为准","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":4000}},"required":["role","content"]}},"temperature":{"type":"number","description":"生成温度（请求级，可选；超安全区间自动收敛；当前引擎不支持透传，已预留并如实标注）"},"top_p":{"type":"number","description":"核采样 top_p（请求级，可选；超安全区间自动收敛；当前引擎不支持透传，已预留并如实标注）"},"max_tokens":{"type":"integer","minimum":1,"description":"生成最大 token 数（请求级，可选；超安全区间自动收敛；当前引擎不支持透传，已预留并如实标注）"},"kb_ids":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"本次调用限定检索的知识库 ID 列表（可选，≤20 个；须在应用授权范围内，越权返回 403「该知识库不在应用的授权范围内」；不传则用应用级授权范围）"},"tools":{"type":"array","maxItems":5,"description":"工具定义（可选，≤5 个；每项 {name, description, parameters(JSON Schema)}；当前引擎不支持，已预留并如实标注，不生效）","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","description":"JSON Schema 形参定义"}},"required":["name","parameters"]}},"response_format":{"type":"object","description":"结构化输出格式（仅支持 {\"type\": \"json_object\"}；当前引擎不支持，已预留并如实标注，不生效）"}},"required":["query"]},"example":{"query":"试用期多久","stream":false}}}},"responses":{"200":{"description":"问答结果（application/json，stream=false）或 SSE 事件流（text/event-stream，stream=true）","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"答案全文（非空）"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"引用来源标题"},"content":{"type":"string","description":"引用片段内容（已脱敏）"},"source":{"type":"string","description":"来源文档标识（引擎文档 ID，兼容旧字段）"},"doc_id":{"type":"string","description":"平台文档 ID（可直接用于原文下载端点）"},"url":{"type":"string","description":"原文链接（URL 摄入=原始公网地址；上传文件=平台下载端点）"},"source_url":{"type":"string","description":"原始来源 URL（仅 URL 摄入且为公网地址时出现）"},"score":{"type":["number","null"],"description":"相关度分数"},"chunk_id":{"type":"string","description":"命中的知识片段 ID（可选，仅部分后端提供）"},"positions":{"type":"array","items":{"type":"string"},"description":"片段在原文中的页码/位置定位（可选，仅部分后端提供）"}},"required":["title","content","source"],"title":"SourceItem"}},"model":{"type":"string","description":"生成模型 / 引擎标识"},"latency_ms":{"type":"integer"},"notice":{"type":"string","description":"空结果提示（仅空结果时出现）"}},"required":["answer","sources","model","latency_ms"]},"example":{"answer":"试用期为 3 个月。","sources":[{"title":"员工手册.pdf","content":"…试用期：3 个月…","source":"doc_123","score":0.91}],"model":"ragflow","latency_ms":2410}},"text/event-stream":{"schema":{"type":"object","description":"每帧一行 `data: <json>\\n\\n`：`{\"token\": \"…\"}` 增量正文；`{\"done\": true, content, sources, model, latency_ms, truncated}` 终态帧（truncated=true 表示流未以引擎终态帧结束，content 为已累计部分；空结果时另含 `notice` 字段）；`{\"error\": \"知识引擎暂时不可用\"}` / `{\"error\": \"知识引擎响应超时\"}` 终止错误帧（与同步路径 502/504 文案一致——流开始后引擎错误只能以带内帧承载）。"},"example":"data: {\"token\":\"试用期\"}\\n\\ndata: {\"done\":true,\"content\":\"试用期为 3 个月。\",\"sources\":[],\"model\":\"ragflow\",\"latency_ms\":2410,\"truncated\":false}\\n\\n"}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"接口未授权 / 应用停用 / 未授权任何空间 / 密钥级权限不足（该密钥 scope 不含本接口）/ 请求 kb_ids 越权（该知识库不在应用的授权范围内）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"该知识库不在应用的授权范围内"}}}},"422":{"description":"参数校验失败（kb_ids 非 UUID/超 20 个等）"},"429":{"description":"调用频率超限（code=42902，含 Retry-After）/ 配额用尽（code=42901，另带 X-Quota-* 响应头）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用配额已用尽","code":42901}}}},"502":{"description":"知识引擎暂时不可用","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"知识引擎暂时不可用"}}}},"504":{"description":"聚合超时（60s）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"知识引擎响应超时"}}}}}}},"/openapi/v1/documents":{"post":{"tags":["数据面"],"summary":"上传知识文档（写入能力，默认关闭、运营按应用授予）","description":"把文档写入应用**已授权**的知识库：multipart 文件与 JSON `{kb_id, source_url}` **二选一**。返回 `task_id`，用 `GET /openapi/v1/documents/tasks/{task_id}` 轮询状态。\n\n前置条件（缺一不可）：① 应用已由平台运营授予写入能力（`write_enabled`，**默认关闭**）；② 目标 `kb_id` 在应用授权范围内；③ 扩展名在 `pdf / docx / xlsx / txt / md / csv` 内，大小 ≤ 20MB。\n\n写入配额与检索**共用同一配额桶**：每次提交预留 1 次调用额度，超限 429。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"kb_id":{"type":"string","description":"目标知识库ID"},"file":{"type":"string","format":"binary","description":"文档文件（pdf / docx / xlsx / txt / md / csv，≤20MB）"}},"required":["kb_id","file"]}},"application/json":{"schema":{"type":"object","properties":{"kb_id":{"type":"string","description":"目标知识库ID"},"source_url":{"type":"string","description":"文档 URL（http/https）"}},"required":["kb_id","source_url"]},"example":{"kb_id":"a1b2c3d4-...","source_url":"https://example.com/docs/guide.pdf"}}}},"responses":{"200":{"description":"任务已创建（异步解析入库）","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string","description":"写入任务ID（轮询用）"},"status":{"type":"string","const":"queued"},"doc_id":{"type":["string","null"],"description":"文档ID（创建时恒为 null；任务终态后从轮询响应获取，用于删除/恢复寻址）"}},"required":["task_id","status","doc_id"]},"example":{"task_id":"2f1e...","status":"queued","doc_id":null}}}},"400":{"description":"文件类型 / 大小 / 来源参数不合法","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"写入能力未开通（联系平台运营） / 知识库不在应用授权范围 / 密钥级权限不足（该密钥 scope 不含 upload）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"写入能力未开通，请联系平台运营"}}}},"422":{"description":"参数校验失败（file 与 source_url 二选一；kb_id 格式错误等）"},"429":{"description":"调用频率超限（code=42902）/ 配额用尽（code=42901，含 Retry-After 与 X-Quota-* 响应头）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用配额已用尽","code":42901}}}}}},"get":{"tags":["数据面"],"summary":"列出本应用写入的文档（source=openapi）","description":"列出本应用经开放平台写入的文档（含软删墓碑行与失败任务）。需 read scope。","security":[{"bearerAuth":[]}],"parameters":[{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"openapi = 仅本应用写入（当前唯一支持取值）"},{"name":"kb_id","in":"query","required":false,"schema":{"type":"string"},"description":"按知识库过滤"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","default":100,"maximum":200},"description":"每页条数（默认 100，上限 200）"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"keyset 游标"},{"name":"updated_after","in":"query","required":false,"schema":{"type":"string"},"description":"ISO8601，只返回 updated_at >= 该值的文档"}],"responses":{"200":{"description":"文档列表（items / next_cursor / total）"},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"密钥级权限不足（该密钥 scope 不含 read）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"该密钥未授权本接口（缺少 scope: read）"}}}},"429":{"description":"配额用尽 / 限流","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"}}}}}}},"/openapi/v1/documents/{doc_id}/download":{"get":{"tags":["数据面"],"summary":"下载文档原文","description":"按 `doc_id`（检索结果的 `doc_id` / 文档列表的 `doc_id`）下载**本应用写入**的文档原文。\n\n文件类返回文件流（COS 直取或本地文件）；URL 摄入的文档没有平台存储文件，返回 404 并提示改用 `source_url`。需 `read` scope；只做限流，**不消耗调用配额**。软删（墓碑）文档返回 404，恢复后可下载。","security":[{"bearerAuth":[]}],"parameters":[{"name":"doc_id","in":"path","required":true,"schema":{"type":"string"},"description":"文档 ID（取自检索结果或文档列表）"}],"responses":{"200":{"description":"文件流（Content-Disposition: attachment）"},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"密钥级权限不足（该密钥 scope 不含 read）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"该密钥未授权本接口（缺少 scope: read）"}}}},"404":{"description":"文档不存在 / 已删除 / URL 摄入无平台文件 / 文件缺失","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"文档已删除，请先恢复后再下载"}}}}}}},"/openapi/v1/documents/batch":{"post":{"tags":["数据面"],"summary":"批量导入文档（≤50 个文件或 URL）","description":"一次提交多个文档：multipart `files`（≤50 个，总量 ≤200MB）**或** JSON `{kb_id, urls:[...]}`（≤50 条）二选一。\n\n每个文档各自生成一个任务（`task_id`），整批共享一个 `batch_id`；用 `GET /openapi/v1/documents/batches/{batch_id}` 汇总进度，或按 `task_id` 单独轮询。配额按文件计（每个文件 1 次），**配额不足时部分成功**（逐项返回 42901，不整批失败）。需 `upload` scope + 写入能力（write_enabled）。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"文档文件（pdf/docx/xlsx/txt/md/csv，单文件 ≤20MB，总数 ≤50）"},"kb_id":{"type":"string","description":"目标知识库 ID（须在应用授权范围内）"}},"required":["files","kb_id"]}},"application/json":{"schema":{"type":"object","properties":{"kb_id":{"type":"string"},"urls":{"type":"array","items":{"type":"string"},"description":"1~50 条 http/https URL"}},"required":["kb_id","urls"]},"example":{"kb_id":"a1b2c3d4-...","urls":["https://example.com/a.pdf","https://example.com/b.md"]}}}},"responses":{"200":{"description":"逐项结果（整体恒 200；单项失败在 items[].error 里）","content":{"application/json":{"schema":{"type":"object"},"example":{"batch_id":"9f2c…","total":3,"accepted":2,"rejected":1,"items":[{"index":0,"document_name":"a.pdf","ok":true,"task_id":"2f1e…","doc_id":null,"status":"queued"},{"index":2,"document_name":"x.exe","ok":false,"task_id":null,"doc_id":null,"status":"failed","error":{"status":400,"detail":"不支持的文件类型: .exe"}}]}}}},"401":{"description":"凭证无效","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"写入能力未开通 / 知识库不在授权范围 / 密钥 scope 不含 upload","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"422":{"description":"参数校验失败（files 与 urls 未二选一 / 超过 50 个 / urls 非法）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"429":{"description":"限流（整批拒绝）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"}}}}}}},"/openapi/v1/documents/batches/{batch_id}":{"get":{"tags":["数据面"],"summary":"查询批量导入批次进度","description":"按 `batch_id` 汇总本批任务进度：总数 / 各状态计数 / 逐项 `task_id` 与状态。\n\n只返回**本应用**提交的批次（他人批次 404 防枚举）。不计量。状态以任务执行侧落库为准；需要引擎实时进度请用单任务轮询。","security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"批次进度（total / status_counts / progress / finished / items[]）"},"401":{"description":"凭证无效","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"404":{"description":"批次不存在（或不属于本应用）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"批次不存在"}}}}}}},"/openapi/v1/documents/tasks/{task_id}":{"get":{"tags":["数据面"],"summary":"查询知识写入任务状态（进度 / error_log）","description":"按 `task_id` 轮询任务状态：`queued` / `processing` / `done` / `failed`。\n\n进度为**查询时点的引擎实时值**（任务表不持久化进度）；轮询会同步引擎终态；任务仅限创建它的应用查询（他人任务返回 404，防枚举）。本端点不计量。","security":[{"bearerAuth":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"},"description":"POST /openapi/v1/documents 返回的任务ID"}],"responses":{"200":{"description":"任务状态","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string"},"doc_id":{"type":["string","null"],"description":"文档ID（任务已创建知识原子后非空；删除/恢复寻址用，与文档列表同源）"},"status":{"type":"string","enum":["queued","processing","done","failed"]},"progress":{"type":"integer","description":"进度 0-100（引擎实时值；done=100）"},"document_name":{"type":"string"},"source_type":{"type":"string","enum":["file","url"]},"kb_id":{"type":"string"},"error_log":{"type":"string","description":"失败原因 / 降级说明（成功为空串）"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["task_id","doc_id","status","progress","error_log"]},"example":{"task_id":"2f1e...","doc_id":"5f3a...","status":"done","progress":100,"document_name":"guide.pdf","source_type":"file","kb_id":"a1b2...","error_log":"","created_at":"2026-10-10T08:00:00","updated_at":"2026-10-10T08:00:12"}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"404":{"description":"任务不存在（含他人任务，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"422":{"description":"task_id 格式错误"}}}},"/openapi/v1/documents/{doc_id}":{"delete":{"tags":["数据面"],"summary":"软删除本应用写入的文档（可恢复）","description":"打 deleted_at 墓碑 + 删引擎向量（不删物理文件，可恢复）。仅限本应用经开放平台写入的文档；删除豁免配额；幂等（已删再次删仍 200）。需 delete scope + write_enabled。","security":[{"bearerAuth":[]}],"parameters":[{"name":"doc_id","in":"path","required":true,"schema":{"type":"string"},"description":"文档ID（列表接口下发的 doc_id）"}],"responses":{"200":{"description":"软删成功（幂等）"},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"写入能力未开通 / 密钥 scope 不含 delete","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"404":{"description":"文档不存在（含非本应用文档，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"422":{"description":"doc_id 格式错误"}}}},"/openapi/v1/documents/{doc_id}/restore":{"post":{"tags":["数据面"],"summary":"恢复软删的文档（重新入库，doc_id 不变）","description":"复用原 atom 行重新入库（专用 restore 执行器），对外 doc_id 不变、引擎身份变化。恢复按写入计 1 次配额；幂等（未删 restore 仍 200）。需 delete scope + write_enabled。","security":[{"bearerAuth":[]}],"parameters":[{"name":"doc_id","in":"path","required":true,"schema":{"type":"string"},"description":"文档ID"}],"responses":{"200":{"description":"恢复任务已投递（返回 task_id 轮询）"},"400":{"description":"无知识原子无法恢复 / url 来源 SSRF 拒绝"},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"写入能力未开通 / 密钥 scope 不含 delete","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"404":{"description":"文档不存在（含非本应用文档，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"409":{"description":"文档仍在处理中"},"422":{"description":"doc_id 格式错误"},"429":{"description":"配额用尽 / 限流","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"}}}}}}},"/openapi/v1/generate":{"post":{"tags":["数据面"],"summary":"提交商务文档生成任务（异步，需运营授予 generate 接口）","description":"在应用**授权范围**内的知识库检索语料并生成 8 类商务文档（产品介绍/解决方案/技术培训/内部办公/推广方案/政府公文/商业计划书/演示文档），或 `doc_outline` 两阶段大纲。返回 `task_id`，用 `GET /openapi/v1/generate/tasks/{task_id}` 轮询状态与结果。\n\n前置条件：应用已由平台运营在应用治理里把 `/openapi/v1/generate` 加入接口白名单（**默认未授权，fail-closed**）。生成配额与检索/写入**共用同一配额桶**（每次提交预留 1 次额度）。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"产物类型（8 类商务文档之一，或 doc_outline 两阶段大纲）"},"topic":{"type":"string","maxLength":2000,"description":"生成主题/检索 query（可选，缺省取知识库名）"},"kb_ids":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"本次限定检索的知识库 ID（可选，≤20；须在应用授权范围内，越权 403；不传=应用级范围）"},"top_k":{"type":"integer","minimum":1,"maximum":60,"description":"语义检索取回条数（8~60，越界自动收敛）"},"outline":{"type":"object","description":"已确认的大纲（两阶段第二阶段回传；含 sections 时按章节分段生成）"},"target_kind":{"type":"string","description":"目标文档类型（kind=doc_outline 时指定，须为 8 类商务文档之一）"}},"required":["kind"]},"example":{"kind":"product_intro","topic":"我们的知识库产品"}}}},"responses":{"200":{"description":"任务已创建（异步生成）","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string","description":"生成任务ID（轮询用）"},"status":{"type":"string","const":"queued"}},"required":["task_id","status"]},"example":{"task_id":"2f1e...","status":"queued"}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"403":{"description":"接口未授权（默认，须运营授予）/ 知识库不在应用授权范围 / 未授权任何可用知识库 / 密钥级权限不足（缺 generate scope）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"该接口未授权"}}}},"422":{"description":"参数校验失败（kind 非法 / topic 超长 / kb_ids 非 UUID 或超 20 个）"},"429":{"description":"调用频率超限（code=42902）/ 配额用尽（code=42901，含 Retry-After 与 X-Quota-* 响应头）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"},"code":{"type":"integer","description":"业务错误码：42901=周期配额用尽；42902=调用频率超限。其余错误响应无此字段"}},"required":["detail","code"],"title":"ErrorDetailWithCode"},"example":{"detail":"调用配额已用尽","code":42901}}}},"451":{"description":"topic 命中内容安全敏感词（拦截在配额预留前，不消耗配额）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"},"example":{"detail":"内容未通过安全检查"}}}}}}},"/openapi/v1/generate/tasks/{task_id}":{"get":{"tags":["数据面"],"summary":"查询生成任务状态与结果（终态含 result）","description":"按 `task_id` 轮询任务状态：`queued` / `processing` / `done` / `failed`。`done` 时 `result` 字段返回生成结果（已按应用规则脱敏；含 data/provenance 文档级来源清单）。任务仅限创建它的应用查询（他人任务返回 404，防枚举）；本端点不计量。","security":[{"bearerAuth":[]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"},"description":"POST /openapi/v1/generate 返回的任务ID"}],"responses":{"200":{"description":"任务状态与结果","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","done","failed"]},"progress":{"type":"integer","description":"进度 0-100（done=100；单次生成无引擎侧真实进度，其余为 0）"},"kind":{"type":"string"},"result":{"type":"object","description":"生成结果（仅 done 时返回；含 data/provenance 文档级来源清单）"},"error_log":{"type":"string","description":"失败原因（成功为空串）"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["task_id","status","progress","error_log"]},"example":{"task_id":"2f1e...","status":"done","progress":100,"kind":"product_intro","result":{},"error_log":"","created_at":"2026-10-12T08:00:00","updated_at":"2026-10-12T08:00:30"}}}},"401":{"description":"凭证无效（统一文案，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"404":{"description":"任务不存在（含他人任务，防枚举）","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"错误说明"}},"required":["detail"],"title":"ErrorDetail"}}}},"422":{"description":"task_id 格式错误"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"由 `POST /openapi/v1/auth/token` 签发。企业端 / 运营端令牌不能调用本网关。"}}}}