REST API 参考

本页记录当前 Web UI 使用的关键 HTTP 接口，内容来自 services/api/src/http/index.ts 与 packages/schema/src/ 的类型。接口当前没有版本前缀或独立稳定性承诺；仓库内路由和共享 schema 是事实源。面向外部集成时，应固定所使用的 ScienceDiscovery 提交或 Release，并在升级时重新核对。

地址、认证与通用响应

• 本地模式默认基址与绑定地址：http://127.0.0.1:4310。
• Docker 默认发布地址：http://127.0.0.1:4310。
• 默认 JiuwenSwarm 后端下，:4310 是 adapter 对外入口，产品路由转发到 :4410 的 API；带令牌的 GET /agent/info 可查看 executor 与网关连通性。native 模式下 API 直接占用 :4310。详见 Agent 后端。
• GET /health 与 GET /api/health 无需认证。
• MCP OAuth 浏览器回调 GET /api/mcp/oauth/callback 不使用本地 bearer token，而是校验待处理的一次性 OAuth state，并通过 PKCE 交换授权码。
• 其他 /api/* 请求必须携带 Authorization: Bearer <SCIENCE_AGENT_AUTH_TOKEN>。没有默认 token：该变量未设置时，服务端在首次启动生成本地服务访问令牌，打印 Open to sign in 链接与令牌，并保存在 <数据目录>/secrets/auth-token。
• JSON 客户端应发送 Content-Type: application/json；服务端对通用 JSON body 设置 1,500,000 bytes 上限。工作区上传使用 multipart 及独立配额。
• JSON 错误至少包含 {"error":"..."}；部分业务错误还可包含 code 或 details。

通用状态码来自当前路由与错误映射：

健康检查

curl -fsS http://127.0.0.1:4310/health

成功响应为 200，字段包括：

{
  "memoryGraph": "disabled",
  "milestone": "M4",
  "runner": { "status": "ok" },
  "service": "sciencediscovery-api",
  "status": "ok",
  "workspace": {
    "maxFileBytes": 1073741824,
    "maxRequestBytes": 10737418240,
    "maxWorkspaceBytes": 10737418240
  }
}

runner 的完整字段由 Runner 健康响应决定；Runner 不可用时 API 返回 status: "degraded" 和 runner.status: "unavailable"，HTTP 状态仍为 200。workspace.maxFileBytes 与 maxRequestBytes 是上传入口配额，maxWorkspaceBytes 是 Runner 工作区配额；输出限制不在此响应中，层级见配置参考。

Project 与 Session

以下是创建和浏览主流程所需的接口：

最小 Project 请求：

curl -X POST http://127.0.0.1:4310/api/projects \
  -H "Authorization: Bearer ${SCIENCE_AGENT_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Research plan"}'

CreateProjectRequest 的字段是 name: string 与可选 settingsOverrides。CreateSessionRequest 可包含 title、modelId、settingsOverrides、approvalMode、reviewMode、reviewCriteria 和 specialistId；可选字段的精确类型见 packages/schema/src/session.ts。

删除 Project 或 Session 不是无请求体的 DELETE：客户端应先查询对应的 .../deletion-impact，再把服务端给出的 targetId 作为 confirmationId 提交。若目标含活跃运行或确认值不匹配，删除会失败。

Run 与事件

最小 Run 请求只要求 content：

{
  "content": "概括当前研究目标，并给出下一步分析计划"
}

SendMessageRequest 还可包含 annotationIds、references 和 webForceRefresh。SessionRun.status 当前可能为 queued、running、blocked、completed、failed、cancelled 或 interrupted。

演进搜索

/evolve-design 运行的只读视图，以及停止一次运行。搜索由 Agent 通过 create_evolve_run 工具发起，不经由本 API。参见程序演进。

自定义 MCP 服务器与 Inspector

界面操作见配置自定义 MCP。路由位于 services/api/src/http/custom-mcp.ts，请求和响应类型位于 packages/schema/src/custom-mcp.ts。下表接口均需本地服务访问令牌（Bearer token）。

服务器 ID 为 custom- 加 12 位十六进制字符。最多保存 50 台自定义服务器，名称不区分大小写且不能重复。最小停用 HTTP 配置示例：

{
  "name": "Research tools",
  "transport": "http",
  "url": "https://mcp.example.com/mcp",
  "enabled": false,
  "timeoutSeconds": 60,
  "authMode": "headers",
  "headers": {}
}

transport 为 stdio、http 或 sse。STDIO 使用 command、args、cwd、env，HTTP/SSE 使用 url、headers。timeoutSeconds 默认 60，必须为 1-600 的整数。OAuth 模式接受 oauth: {clientId, clientSecret, scope, clientMetadataUrl}，不能同时配置手动 Authorization 请求头。示例 URL 是占位地址，不可直接用于连接。

响应中的 env、headers 只返回键名和值为 null 的映射，不返回秘密值。更新时，null 只保留同名 key 的旧值；字符串（包括 ""）替换旧值，省略映射中的 key 表示删除。因此重命名必须明确提供新值，对原本不存在的 key 传 null 会失败。界面对已保存键名的重命名要求重新填写值，未填时阻止保存。OAuth 的 clientSecret: null 同样保留已保存的值；详情不会返回 access/refresh token。

连接失败可能通过 HTTP 200 测试结果内的 error 返回。进入治理链路后的 Inspector 失败返回 ok: false；无效输入或调用记录建立前的错误可能返回 400，服务器不存在返回 404。不能只根据 HTTP 成功判断工具成功。Inspector 要求服务器已启用、Session 存在且工具已被发现；手动调用会记录审计，但不会替该 Session 的 Agent 启用连接器。

OAuth 浏览器回调

这是上述本地 bearer 认证的例外，不是通用免认证配置接口。OAuth state 一次性使用，10 分钟过期；回调必须来自通过认证的 start 接口发起的流程。清除本地授权不等于撤销服务商端授权。远程 OAuth 端点要求 HTTPS，本机回环 HTTP 可用于开发。

代理配置

以下接口均需 bearer 认证。配置步骤与凭据注意事项见配置网络代理。

kind 只能是 custom_url、environment 或 system；custom_url 创建时必须提供 url。示例：

curl -H "Authorization: Bearer ${SCIENCE_AGENT_AUTH_TOKEN}" \
  http://127.0.0.1:4310/api/proxy/settings

curl -X POST http://127.0.0.1:4310/api/proxy/servers \
  -H "Authorization: Bearer ${SCIENCE_AGENT_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Corporate proxy","kind":"custom_url","url":"http://proxy.company.example:8080"}'

不要把真实代理凭据写入文档、脚本或 shell history。认证设置接口会按当前产品设计返回完整 URL，因此应按凭据管理界面保护 bearer token 和浏览器会话。