API 参考

#基础约定

本指南默认使用 Compose 的公共入口 http://localhost:21108；单独运行 Backend 时，可改为 http://localhost:21109。所有业务 API 使用 /api 前缀。JSON 请求带 Content-Type: application/json；上传使用 multipart/form-data。运行服务的 /openapi.json 提供完整机器可读定义，/docs 打开 Swagger。

表中的 {sid}、{pid}、{did} 分别代表服务端返回的 session_id、project_id、dataset_id；{rid} 为 run_id，{jid} 为 job_id。路径缩写只用于阅读，实际调用时替换为对应标识。以下为主要入口索引，字段约束与完整响应以同一部署的 /openapi.json 为准。

#单用户工作区

公共 /api/* 请求统一绑定到 IGRAPH_ADMIN_USER_ID 指定的默认工作区归属，默认 admin。客户端无需提交 X-User-ID；旧客户端即使发送该头，也会被服务端替换为固定归属，不能用它切换账号。本接口无请求体，返回工作区状态与可用模型信息，不进行用户认证，也不颁发登录令牌。

{
  "valid": true,
  "single_user": true,
  "user_id": "admin",
  "is_admin": true,
  "available_models": [
    "CONFIGURED_MODEL"
  ],
  "default_model": "CONFIGURED_MODEL"
}

上例的 CONFIGURED_MODEL 是占位符，实际模型以工作区响应和 GET /api/models 为准。旧 POST /api/auth/validate 仅保留为隐藏兼容入口，返回相同工作区信息；/api/admin/users 及其用户管理操作已移除。is_admin 是内部兼容字段，不表示存在管理员登录流程。

模型 API Key 和 IGRAPH_CONTROL_SERVICE_KEY 仍分别用于模型供应商连接与内部服务校验。项目、会话、数据集和文件的范围检查仍然生效。单用户应用默认通过本机回环地址或 SSH 隧道访问；没有登录页面并不意味着应把内部服务直接暴露到公网。

#创建会话

{
  "client_session_id": "799888e3-5ae2-43ad-bec3-5b1e8e64fa25",
  "reasoning_mode": "direct",
  "planning_mode": "auto"
}

成功响应包含 success、session_id，以及当前 model、project_id、active_dataset_id 等信息。复用客户端 ID 时可能返回 reused: true。创建会话后调用 chat/stream 发送消息。

#会话与运行接口

项目和数据集接口保留独立作用域：项目数据使用 /api/projects/{pid}/datasets，个人数据使用 /api/personal-datasets。项目下的会话与训练实验可分别从 conversations 和 training-runs 子路径读取；训练接口提供已记录实验的汇总，不会仅因读取列表而启动训练。

工作区、记忆与技能也有公共 API。技能上传使用 multipart/form-data 的 file 字段，支持 .md 和 .zip，当前 Backend 限制为 2 MiB。候选批准与工具执行审批是两个不同流程。

/api/export/sft 支持 format=alpaca、sharegpt 或 raw，以及 min_turns、require_tool_calls 筛选参数；返回包含 items 的 JSON。它导出已有记录，不代表样本已经经过质量筛选或可以直接用于训练。此接口未在当前前端提供独立的 SFT 导出按钮；文件下载、报告展示和会话样本导出应分别理解。

#上传数据集

数据集上传使用 multipart/form-data。至少提供一个 file 或 files 文件字段；files 可重复用于多文件上传。多表 CSV 可连同描述关系的 schema JSON 组成同一数据集，具体支持的组合以返回的验证结果为准。项目和个人作用域使用各自的上传地址。

curl -X POST "http://localhost:21108/api/projects/PROJECT_ID/datasets" \
  -F "files=@customers.csv" \
  -F "files=@orders.csv" \
  -F "files=@schema.json" \
  -F "name=Commerce tables"

聊天附件另用 POST /api/sessions/{sid}/upload 的 file 字段。响应中的 file_token 用于后续聊天请求，workspace_path 表示工作区文件位置；不能用浏览器本地路径代替 file_token。CSV、SQL、TXT 附件可登记为待构图数据源。上传成功、源数据预览成功、构图完成和当前会话加载图，是四个不同状态。

源数据预览地址是 /api/projects/{pid}/datasets/{did}/construction/source-preview，个人数据对应 /api/personal-datasets/{did}/construction/source-preview。该只读接口可在构图前调用；CSV 可携带 delimiter。结果中的 tables、text、limits 和 warnings 表示有上限的表格样例或文本片段。SQL 字段说明标明注释、结构信息或未提供说明，不能把结构推断当成业务定义；预览解析成功也不保证 SQL 方言适用于后续构图。

#错误与重试

FastAPI 的 detail 可能是字符串、结构化对象或验证错误数组，不应假定统一错误 envelope。流建立后的失败需结合 SSE 终止事件、快照与 control 状态处理。