API 介绍¶

Datus REST API 将 Agent 的 chat 循环、知识库 explorer、数据库 catalog 与语义模型管理以 HTTP 接口的形式对外暴露。通过 datus-api 命令启动。

API 服务与 datus CLI、datus-mcp MCP 服务共享同一套配置、知识库与 Agent 能力 — 三种入口,同一个引擎。

入口	适用场景
CLI(`datus`)	本地交互式开发
MCP(`datus-mcp`)	嵌入到其他 Agent 中
REST API(`datus-api`)	Web 前端、服务化、自动化

鉴权模型¶

开源版本采用基于请求头的身份识别方案,无 token 概念。调用方通过 X-Datus-User-Id 请求头标识自己,值需匹配 ^[A-Za-z0-9_-]+$。未提供时请求落入默认未隔离的会话;提供时,该 user id 用于隔离各用户的会话与工具状态。

X-Datus-User-Id: alice

SQL policy 使用单独的请求 principal。启用 agent.sql_policy.enabled 后，请通过 X-Datus-Principal 传入业务范围字段， header 值必须是 JSON object，例如 {"market_code":"MKT300"}。X-Datus-User-Id 不会写入 SQL policy principal。注意：X-Datus-Principal 中不允许包含 user_id 字段；该字段保留给 X-Datus-User-Id，否则会触发 400 校验错误。详见 SQL Policy。

Datasource 隔离由 --datasource CLI 参数(或 DATUS_DATASOURCE 环境变量)单独控制,决定加载 agent.yml 中的哪个 datasource 的数据库与知识库。

响应封装¶

绝大多数 JSON 响应都包裹在统一的 Result[T] 结构中:

{
  "success": true,
  "data":    { ... },
  "errorCode":    null,
  "errorMessage": null
}

字段	类型	说明
`success`	bool	成功为 `true`,失败为 `false`
`data`	object	接口专属业务数据,失败时为 `null`
`errorCode`	string	稳定的机器可读错误码
`errorMessage`	string	人类可读错误描述

流式接口(/chat/stream、/chat/resume)返回 text/event-stream,不使用 Result 包装,详见 Chat。

全局 URL 前缀¶

所有 v1 接口位于 /api/v1 前缀下;健康检查 /health 与 OpenAPI/Swagger UI(/docs、/openapi.json) 位于应用根路径。

问题排查¶

诊断服务器异常的方法：

请求卡住——如果一个请求迟迟不返回但 GET /health 仍能正常响应，那几乎总是某个协程被挂起，而非事件循环被阻塞。向服务器发送 SIGUSR1（kill -USR1 <pid>），即可转储所有存活异步任务以及各自被挂起的最内层栈帧。详见调试 — SIGUSR1 任务转储。

下一步¶

部署 — 安装并启动 API 服务
Chat — Chat 接口与 SSE 流式协议
知识库 — 知识库构建与平台文档接口（SSE 流式）
调试 — 用 SIGUSR1 异步任务转储诊断卡住的请求