企业知识库 API 接入文档

curl -X POST https://echoai.best/api/v1/external/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"差旅费报销有什么规定？"}'

import os, requests

resp = requests.post(
    "https://echoai.best/api/v1/external/query",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"question": "差旅费报销有什么规定？"},
    timeout=300,
)
data = resp.json()
print(data["answer"])

{
  "trace_id": "58b70c12-…",
  "answer": "……模型生成的回答……",
  "citations": [
    { "source": "index.md", "filename": "index.md" }
  ],
  "usage": { "input_tokens": 3, "output_tokens": 34, "total_tokens": 37 },
  "pricing": { "model": "openai/gpt-6.1-sol", "currency": "USD" }
}

curl -X POST https://echoai.best/api/v1/external/sources \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submit-001" \
  -d '{
    "knowledge_base_id": "<知识库ID>",
    "filename": "员工手册.md",
    "content": "# 员工手册\n正文内容……",
    "content_type": "text/markdown"
  }'

{
  "document_id": "2991d3b0-…",
  "version_id": "bcabb7fc-…",
  "version": 1,
  "filename": "员工手册.md",
  "ingestion_job_id": "ad3adec1-…",
  "ingestion_status": "queued"
}

curl -X POST https://echoai.best/api/v1/external/changes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_id": "<知识库ID>",
    "knowledge_item_id": "<可选，要修改的知识条目ID>",
    "title": "员工手册 · 更新报销标准",
    "proposed_content": "修改后的完整内容……"
  }'

你可以调用「飞链企业知识库」的外部 API：查资料、上传资料、提交修改。

【鉴权】所有请求都带同一个请求头：
  Authorization: Bearer $API_KEY
  Content-Type: application/json

【一、问答】需要资料时先查知识库，不要凭记忆作答
  POST https://echoai.best/api/v1/external/query
  Body: {"question": "要问的问题"}
  返回 answer（可直接使用）和 citations（命中的来源文件）。
  这是同步接口，通常 20~60 秒，超时请设置到 300 秒以上。
  如果 answer 明确说明知识库没有相关内容，如实告知用户，不要编造。

【二、上传资料】变成知识库的来源文件，会被自动编排成知识
  POST https://echoai.best/api/v1/external/sources
  Body: {"knowledge_base_id": "<KB>", "filename": "文件名.md",
         "content": "完整文本", "content_type": "text/markdown"}
  返回 201 和 ingestion_job_id，状态是 queued。
  **这是异步的**：返回成功只代表任务已入队，内容还没进知识库，要等编排完成，
  不要紧接着就用问答接口验证刚上传的内容。
  建议带 Idempotency-Key 头（任意唯一字符串），重试时保持不变，可避免重复入库。

【三、修改已有知识】进入审批流
  POST https://echoai.best/api/v1/external/changes
  Body: {"knowledge_base_id": "<KB>", "knowledge_item_id": "<可选>",
         "title": "变更标题", "proposed_content": "修改后的完整内容"}
  返回 201，状态 submitted。
  **不会立即生效**，必须有人在管理台「审批发布」中通过并发布。
  所以提交完必须告诉用户：「已提交到审批队列，需要你在管理台发布后才生效」。

【必须遵守】
  1. 一次提交一份文件或一条变更，不要合并成一大堆。
  2. 不要上传密钥、口令、身份证号、手机号等敏感信息。
  3. 修改已有内容前，先用问答接口确认现有内容，不要凭猜想覆盖。
  4. 每次写入后如实报告：上传说明「已入队，等待编排」；变更说明「待人工发布」。
  5. 限流：写入 30 次/分钟、1000 次/天，批量操作请分批。

【凭证】
  API_KEY=<kb_ 开头的密钥>
  知识库ID=<目标知识库的 ID>