01
开始接入
在「平台管理」中为租户或子账号创建 API Key，并按用途选择权限。
Key 自动识别所属租户。请求中无需也不能传递租户 ID；不同 Key 的会话记录和知识库数据彼此隔离。
GET
/api/v1/auth-checkchat:use检查 API Key 是否可用，适合服务启动时做连通性校验。
curl https://knowbase.ac.cn/api/v1/auth-check \
-H "Authorization: Bearer $KNOWLEDGE_API_KEY"02
流式问答
新接入建议使用 SSE。调用方自行生成并长期保存会话 UUID。
POST
/api/v1/conversations/{conversation_id}/messages/streamchat:use- external_user_id
- 必填。业务系统内的用户标识，同一 Key 下保持稳定。
- content
- 必填。用户问题，1-4000 字符。
- config
- 新接入无需传递。对话 Prompt 在创建 Key 时绑定。
curl -N -X POST "https://knowbase.ac.cn/api/v1/conversations/$CONVERSATION_ID/messages/stream" \
-H "Authorization: Bearer $KNOWLEDGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"external_user_id":"user_123","content":"如何办理售后？"}'SSE 事件
start 会话开始delta 增量文本，字段 contentcitation 引用片段done 已完成error 模型服务异常兼容接口
POST /api/chat 接收 {"question":"...","conversationId":"UUID"}，返回一次性 {"content":"..."}。新服务建议使用上方 SSE 接口。03
会话历史
仅能读取当前 API Key 自己创建的会话，避免跨服务访问。
GET
/api/v1/conversations/{conversation_id}/messagesconversation:read:self必填查询参数：external_user_id。可选：limit（1-100）、cursor。返回 items 与 next_cursor。
curl "https://knowbase.ac.cn/api/v1/conversations/$CONVERSATION_ID/messages?external_user_id=user_123&limit=50" \
-H "Authorization: Bearer $KNOWLEDGE_API_KEY"04
知识库文档
文档异步解析和向量化，上传成功后轮询列表中的 state 至 ready。
GET
/api/v1/admin/documents列表。支持 name、state、limit、cursordocument:readPOST
/api/v1/admin/documents上传 Markdown 文件，表单字段为 filedocument:uploadGET
/api/v1/admin/documents/{id}文档详情document:readGET
/api/v1/admin/documents/{id}/chunks已解析切片document:readPUT
/api/v1/admin/documents/{id}用新的 file 完整替换document:replacePOST
/api/v1/admin/documents/{id}/reindex重新建立索引document:reindexDELETE
/api/v1/admin/documents/{id}删除文档document:deletecurl -X POST https://knowbase.ac.cn/api/v1/admin/documents \
-H "Authorization: Bearer $KNOWLEDGE_API_KEY" \
-F "file=@产品说明.md"05
Prompt
Prompt 名称在当前租户内唯一。系统默认 Prompt 所有人可见，仅系统管理员可以编辑。
GET
/api/v1/prompts获取当前租户 Prompt 列表prompt:readPOST
/api/v1/prompts创建，参数：name、contentprompt:writeGET
/api/v1/prompts/{id}获取详情prompt:readPATCH
/api/v1/prompts/{id}修改 name 或 contentprompt:writeDELETE
/api/v1/prompts/{id}删除租户自定义 Promptprompt:writecurl -X POST https://knowbase.ac.cn/api/v1/prompts \
-H "Authorization: Bearer $KNOWLEDGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"简洁客服","content":"使用简洁、自然的客服语气回答。"}'06
错误码
错误响应为 JSON。请根据 HTTP 状态码和 code 处理。
401
UNAUTHENTICATEDKey 缺失、错误、已禁用或所属租户停用。403
FORBIDDENKey 未配置该接口所需权限。404
DOCUMENT_NOT_FOUND / PROMPT_NOT_FOUND资源不存在或不属于当前租户。409
DOCUMENT_CONTENT_ALREADY_EXISTS相同内容已入库，响应附带已有文档 ID。422
VALIDATION_ERROR请求字段、UUID 或参数范围不正确。503
MODEL_PROVIDER_ERROR上游模型临时不可用，可稍后重试。API Key 仅保存在服务端环境变量或密钥管理系统中，不要放进浏览器、移动端或日志。