REST API 参考 | SAG Wiki

SAG API 是完整产品的自托管 HTTP 边界，默认地址为 http://localhost:8000/api/v1。启动实例后，可在 /docs 查看交互式 OpenAPI，在 /openapi.json 获取机器可读 Schema。

认证

本地身份登录会返回 JWT：

curl -s http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"Developer"}'

后续大多数请求携带：

Authorization: Bearer <SAG_TOKEN>

POST /auth/register 受 SAG_ALLOW_REGISTRATION 控制；默认本地身份引导不依赖开放邮箱注册。

资源地图

领域	前缀	主要能力
系统	`/system`	health、ready、capabilities、模型与偏好设置
身份	`/auth`	login、register、me
信源	`/sources`	连接器、CRUD、同步、chunk 原文、信源 MCP 配置
文档	`/sources/{id}/documents`	上传、文本写入、预览、解析结果、暂停、恢复、重处理、删除
任务	`/jobs/{job_id}`	后台任务状态
检索	`/search` 与 `/sources/{id}/search`	全局或信源内 vector/multi 检索
图谱	`/sources/{id}/entities` 与 `/graph`	event-entity 结构
Agent	`/agents`	Agent、绑定、会话、消息、ask 与运行取消
OpenAI	`/openai/{agent_id}/chat/completions`	兼容 Chat Completions 与 SSE
知识宇宙	`/universe`	manifest、expand、timeline、node detail、exploration
MCP	`/mcp/`	Streamable HTTP 知识工具

创建信源

curl -s -X POST http://localhost:8000/api/v1/sources \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product docs",
    "description": "产品与 API 文档",
    "connector_kind": "file_upload",
    "config": {}
  }'

返回的 SourceOut 包含 id、状态、文档数、chunk 数、event 数和时间戳。

写入文本

text 与 messages 二选一：

curl -s -X POST \
  http://localhost:8000/api/v1/sources/<SOURCE_ID>/documents/ingest \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "SAG",
    "text": "SAG 使用 event-entity 索引与查询时动态超边。"
  }'

写入由后台任务继续处理。DocumentOut.status 变为 ready 后再期待稳定检索结果。

执行检索

全局检索：

curl -s -X POST http://localhost:8000/api/v1/search \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "SAG 如何检索知识？",
    "source_ids": ["<SOURCE_ID>"],
    "strategy": "multi",
    "top_k": 5,
    "save_exploration": false
  }'

信源内检索使用 POST /sources/{source_id}/search，请求体不需要 source_ids。

SearchRequest 约束

字段	类型	约束
`query`	string	1 到 4000 字符
`strategy`	string	`vector` 或 `multi`，可省略使用默认值
`top_k`	integer	1 到 50
`source_ids`	string[]	仅全局接口，最多 256 个
`save_exploration`	boolean	仅全局接口，是否保存探索会话

健康与就绪

GET /system/health 表示 HTTP 进程可响应。
GET /system/ready 表示关键依赖已经初始化，可接收正常业务流量。
GET /system/capabilities 返回当前知识引擎与可用能力。

容器健康检查使用 ready 端点。负载均衡和编排系统也应以 ready 作为接流量依据。

错误处理

验证错误遵循 FastAPI/Pydantic 的结构化响应。后台处理错误会记录在文档与任务状态中；SQL 与本地存储细节会在 API 边界被脱敏，完整堆栈仅保留在服务日志。

自定义前端与 API 不同源时，将前端 Origin 加入 SAG_CORS_ORIGINS。不要用 * 与凭据请求组合来绕过配置。