# API 参考

面向客户端的 Backend HTTP 接口：默认工作区、项目、会话、数据集、构图、文件、记忆与技能。示例请求发送到已运行的 iGraph 服务，文档站本身不执行 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 为准。

## 单用户工作区

**GET** `/api/workspace`

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

```json
{
  "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 隧道访问；没有登录页面并不意味着应把内部服务直接暴露到公网。

## 创建会话

**POST** `/api/sessions`

| 字段 | 类型 / 默认值 | 含义 |
| --- | --- | --- |
| client_session_id | UUID string \| null | 可选客户端幂等 UUID，最长 64 字符；非 UUID 返回 400。 |
| model | string \| null | 可选模型 ID；使用当前工作区可用、已启用且连接配置完整的模型。 |
| project_id | string \| null | 项目归属；null 为非项目会话。 |
| active_dataset_id | string \| null | 可选当前数据集；必须属于会话可访问的工作区和项目范围。 |
| initial_message_preview | string / "" | 最长 1000 字符；作为会话标题等元信息。 |
| reasoning_mode | "direct" \| "staged" / "direct" | 推理模式。 |
| planning_mode | "never" \| "auto" \| "always" / "auto" | 规划策略。 |

```json
{
  "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 发送消息。

## 会话与运行接口

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET / POST | /api/sessions | 列出 / 创建默认工作区的会话 |
| POST | /api/sessions/{sid}/activate | 激活会话并恢复可用状态 |
| GET | /api/sessions/{sid}/messages | 读取持久化消息与可恢复的界面内容 |
| GET | /api/sessions/{sid}/info | 会话信息、活动数据和运行状态 |
| GET | /api/sessions/{sid}/context-usage | 上下文用量信息 |
| PATCH | /api/sessions/{sid} | 更新会话名称等元数据 |
| PATCH | /api/sessions/{sid}/model | 切换当前工作区可用的模型 |
| PATCH | /api/sessions/{sid}/dataset | 更新会话数据集绑定 |
| PATCH | /api/sessions/{sid}/reasoning-mode | 更新推理模式 |
| PATCH | /api/sessions/{sid}/planning-mode | 更新规划模式 |
| DELETE | /api/sessions/{sid} | 删除会话；活动任务可能要求先停止 |
| POST | /api/sessions/{sid}/chat/stream | 发送问题并接收 SSE |
| POST | /api/sessions/{sid}/feedback/stream | 提交工具审批决定并继续原运行 |
| POST | /api/sessions/{sid}/runs/{rid}/resume | 从 last_event_index 继续观察已有运行 |
| GET | /api/sessions/{sid}/runs/{rid}/snapshot | 读取阶段快照；检查 snapshot_complete |
| GET | /api/capabilities | 读取停止与最新一轮编辑的能力开关 |
| POST | /api/sessions/{sid}/runs/cancel | 停止指定运行，需要启用 run_cancel_v1 |
| GET | /api/sessions/{sid}/runs/control | 按 run_id 或 start_request_id 查询控制状态 |
| POST | /api/sessions/{sid}/jobs/{jid}/cancel | 停止指定后台作业，需要启用 job_cancel_v1 |
| GET | /api/sessions/{sid}/jobs/{jid}/control | 查询作业停止与持久化状态 |

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

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET / POST | /api/projects | 列出 / 创建项目 |
| GET / PATCH / DELETE | /api/projects/{pid} | 查看 / 修改 / 删除项目 |
| GET | /api/projects/{pid}/conversations | 项目会话列表 |
| GET | /api/projects/{pid}/training-runs | 项目训练记录与配置、指标、模型信息 |
| GET | /api/server-datasets | 列出服务器预置数据源 |
| POST | /api/projects/{pid}/datasets/from-server | 将可访问的服务器数据源加入项目 |
| GET / POST | /api/models/custom | 列出 / 保存工作区自定义模型配置 |
| DELETE | /api/models/custom/{model_id} | 删除工作区的自定义模型配置 |
| GET | /api/models | 读取模型目录与默认模型 |
| PUT | /api/models/default | 设置默认模型 |
| GET / POST | /api/model-providers | 列出 / 保存模型服务提供商 |
| GET | /api/construction-models | 读取可选构图模型 |
| GET / POST | /api/construction-model-settings | 读取 / 保存独立构图模型连接设置 |

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

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | /api/sessions/{sid}/workspace/files | 列出可见上传文件与已发布结果文件 |
| GET | /api/sessions/{sid}/workspace/derived/{artifact_path} | 通过会话与文件范围校验后下载 Derived 结果 |
| GET / POST | /api/memory | 查询 / 创建记忆；GET 支持 scope、query、limit |
| PATCH / DELETE | /api/memory/{memory_id} | 修改 / 删除记忆 |
| GET | /api/memory/events | 读取记忆相关事件 |
| GET | /api/memory/usage | 读取记忆用量信息 |
| GET / POST | /api/skills | 列出 / 创建技能 |
| POST | /api/skills/upload | 上传技能文件或归档 |
| GET / PUT / DELETE | /api/skills/{name} | 读取全文 / 编辑 / 删除技能 |
| POST | /api/skills/{name}/approve | 批准候选技能 |
| POST | /api/skills/{name}/reject | 拒绝候选技能 |
| GET | /api/export/sft | 导出默认工作区已有会话中的输入输出样本 |

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

- [工作台操作](/zh/workspace/): 查看上述能力在当前界面中的入口与操作流程。
- [流式协议](/zh/streaming/): 请求标识、恢复游标、取消状态与审批反馈。

## 上传数据集

**POST** `/api/projects/{project_id}/datasets`

**POST** `/api/personal-datasets`

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

| 字段 | 说明 |
| --- | --- |
| file / files | 上传一个或多个文件，至少一项必填 |
| csv_schema | 可选的 CSV schema JSON 文本 |
| name / description | 可选的数据集名称和描述 |
| session_id | 可选关联会话，仍需通过归属校验 |
| set_as_default | 仅项目上传支持；默认 false |

```bash
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 方言适用于后续构图。

## 错误与重试

| 状态 | 常见含义 | 客户端处理 |
| --- | --- | --- |
| 403 | 内部服务凭据或数据范围检查未通过 | 检查错误 detail、内部服务密钥和项目 / 会话归属；无需重新登录 |
| 404 | 资源不存在或不可访问 | 核对资源 ID 与工作区 / 项目 / 会话范围；已移除的用户管理入口也返回 404 |
| 409 | 状态或图 revision 冲突 | 重新读取状态后再操作，勿盲目重试写入 |
| 422 | 参数验证失败 | 检查响应 detail 与字段类型 |
| 429 | 构图容量已满：construction_capacity_exhausted | 本次未启动，退避后重试。 |
| 504 | 构图仍在运行或未确认：construction_running_unconfirmed | 先读取构图状态，避免超时后立即重复构图。 |

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

> **传输成功与业务成功**
> HTTP 200 或已取得 job_id 不足以证明分析完成。继续检查 success、构图状态、作业终态及最终结果；异步提交仅表示已受理。解析失败、未支持的输入或无可用结果，应作为明确失败处理。