跳转到内容
GPUPlane

REST API 参考

所有 REST 端点挂载在 /api/v1 下。CLI、Web UI、MCP 适配器都基于这组 API。

鉴权

Section titled “鉴权”

统一使用 Bearer token：

Terminal window
curl -H "Authorization: Bearer <token>" http://localhost:8600/api/v1/status

token scope 分四级：

scope 权限
read 读取所有非敏感资源
write 包含 read，并可提交/取消 job、创建 project/experiment、触发备份等
sdk 运行侧写入：创建 run、批量写入 metrics、注册 checkpoint、上报 event
agent Agent WebSocket 网关接入

write 可兼容需要 read、sdk、agent 的端点。GET /health 无需鉴权。

统一错误格式

Section titled “统一错误格式”

所有错误返回统一 envelope：

{
  "error": {
    "code": "not_found",
    "message": "job 01J9... not found",
    "details": {}
  }
}

常见 code：not_found、conflict、validation_error、unauthorized、forbidden、unavailable。Pydantic 校验失败返回 422 validation_error。

分页

Section titled “分页”

列表端点通常支持 limit 参数，默认在 50–200 之间，上限 500–1000。当前只有 /jobs 额外支持 before 游标（毫秒时间戳）。其余列表按 created_at DESC 返回固定条数。

SSE 流

Section titled “SSE 流”

以下端点返回 text/event-stream：

端点 用途
GET /jobs/{job_id}/logs/stream 实时日志行，带一段最新 tail
GET /events/stream 实时事件流，可按 severity 过滤

心跳线为 : heartbeat。客户端需处理断线重连。

端点列表

Section titled “端点列表”

健康与总览

Section titled “健康与总览”
方法 路径 说明
GET /health Server 健康与版本
GET /auth/whoami 当前 token 的 scope 与名称
GET /status 节点总数/在线数、各状态 job 数、正在运行的 job
POST /admin/backup 在线备份 SQLite，返回备份文件路径和大小

节点（node）

Section titled “节点（node）”
方法 路径 说明
GET /nodes 列出所有节点，含 slots 与 busy 状态
GET /nodes/{node_id} 节点详情
GET /nodes/{node_id}/metrics 节点系统指标序列（GPU util/显存/温度等）
GET /nodes/{node_id}/snapshot 最近 60s 内各指标最新值，用于 dashboard 卡片

任务（job）

Section titled “任务（job）”
方法 路径 说明
POST /jobs 提交 job（write）
GET /jobs?status=&limit=&before= 列出 job；支持状态过滤与 before 时间游标
GET /jobs/{job_id} job 详情；read scope 隐藏 env 值
POST /jobs/{job_id}/cancel 请求取消 job（write）
POST /jobs/{job_id}/retry 将 terminal/LOST job 重新置为 QUEUED（write）
GET /jobs/{job_id}/logs?stream=&tail= tail 日志
GET /jobs/{job_id}/logs/stream SSE 实时日志
GET /jobs/{job_id}/runs 该 job 产生的所有 run 尝试

运行（run）

Section titled “运行（run）”
方法 路径 说明
POST /runs SDK 或导入流程创建 run（sdk）
POST /runs/{run_id}/finish 结束 run，状态为 SUCCEEDED/FAILED/CANCELLED/IMPORTED（run ingest token）
GET /runs?experiment_id=&project_id=&job_id=&status=&limit= 列出 run
GET /runs/{run_id} run 详情
GET /runs/{run_id}/summary run summary
GET /runs/{run_id}/metrics?names=&window_s=&step_from=&step_to=&limit= 查询指标序列
POST /runs/metrics:query 批量查询多个 run 的指标 {run_ids, names?, step_from?, step_to?, limit?}，按 run id 键控返回（叠加图一次取数）
GET /runs/{run_id}/metrics/stream?names= 指标点实时推送（SSE，read）；控制台配合 step_from 水位轮询修复丢点
POST /runs/{run_id}/metrics:batch 批量写入指标点，幂等按 (run_id, seq)（run ingest token）

Metric 定义与 primary metric

Section titled “Metric 定义与 primary metric”
方法 路径 说明
GET /metric-definitions?project_id=&experiment_id= 列出 metric 定义
PUT /metric-definitions/{name:path} 创建或更新 metric 定义（write）
PATCH /metric-definitions/{name:path} 修改 metric 元数据（write）
PUT /primary-metric 设置 global/project/experiment 的 primary metric（write）

Project / Experiment

Section titled “Project / Experiment”
方法 路径 说明
GET /projects 列出 project
POST /projects 创建 project（write）
GET /projects/{project_id} project 详情
PATCH /projects/{project_id} 更新 project（write）
DELETE /projects/{project_id} 删除空 project（write）
GET /experiments?project_id= 列出 experiment
POST /experiments 创建 experiment（write）
GET /experiments/{experiment_id} experiment 详情
PATCH /experiments/{experiment_id} 更新 experiment（write）
DELETE /experiments/{experiment_id} 删除空 experiment（write）
GET /experiments/{experiment_id}/runs?limit= experiment 下的 run

事件（event）

Section titled “事件（event）”
方法 路径 说明
POST /runs/{run_id}/events SDK 上报自定义事件（run ingest token）
GET /events?run_id=&job_id=&node_id=&type=&severity=&limit= 列出事件
GET /events/stream SSE 实时事件流

Checkpoint 与评估

Section titled “Checkpoint 与评估”
方法 路径 说明
POST /runs/{run_id}/checkpoints 注册 checkpoint（run ingest token）
GET /runs/{run_id}/checkpoints 列出 run 的 checkpoint
GET /checkpoints:recommend?run_id=&experiment_id=&metric=&suite=&dataset=&dataset_version= 按 primary metric 推荐最佳 checkpoint
GET /checkpoints/{ckpt_id} checkpoint 详情
POST /checkpoints/{ckpt_id}/evaluations 为 checkpoint 创建 EVALUATE job（write）
GET /checkpoints/{ckpt_id}/evaluations checkpoint 的评估列表
GET /evaluations?run_id=&checkpoint_id= 列出 evaluation
GET /evaluations/{eval_id} evaluation 详情

语义层（semantics）

Section titled “语义层（semantics）”
方法 路径 说明
GET /runs/{run_id}/diagnosis 运行诊断：进度、收敛、异常、下一步建议
GET /runs/compare?ids=&metric=&suite=&dataset=&dataset_version= 多 run 对比，按 primary metric 选出最佳
GET /checkpoints/compare?ids=&metric=&suite=&dataset=&dataset_version= 多 checkpoint 对比
GET /experiments/{experiment_id}/best-checkpoint?metric=&suite=&dataset=&dataset_version= experiment 内最佳 checkpoint
GET /runs/{run_id}/failure 失败原因解释（OOM/NaN/断开等）

Agent 网关

Section titled “Agent 网关”
方法 路径 说明
WS /agent/ws Agent 长连接，用于心跳、job 状态同步、日志推送

示例

Section titled “示例”

提交 job：

Terminal window
curl -H "Authorization: Bearer $GPUCTL_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST http://localhost:8600/api/v1/jobs \
  -d '{
    "name": "mnist",
    "command": ["python", "train.py", "--epochs", "5"],
    "working_dir": "/home/eric/jobs/mnist",
    "type": "TRAIN",
    "runner": "process",
    "resources": {"gpu": 1, "cpu_only": false},
    "priority": 100,
    "project": "cv",
    "experiment": "mnist-v1"
  }'

查询指标：

Terminal window
curl -H "Authorization: Bearer $GPUCTL_TOKEN" \
  "http://localhost:8600/api/v1/runs/01J9.../metrics?names=train/loss,eval/loss"

推荐 checkpoint：

Terminal window
curl -H "Authorization: Bearer $GPUCTL_TOKEN" \
  "http://localhost:8600/api/v1/checkpoints:recommend?experiment_id=01J9..."

设计稿与源码的出入

Section titled “设计稿与源码的出入”

对照 docs/03-system-design.md §11.1：

  • /webhooks 端点：设计稿列出 POST/DELETE /webhooks，源码中不存在。
  • 分页：设计稿写“cursor 分页”，源码当前仅 /jobs 支持 before 游标，其余列表使用 limit 限制条数。
  • Agent WebSocket：设计稿列在 REST 表格中，实为 WebSocket 端点 /api/v1/agent/ws。
  • run 的 finish 端点：设计稿未显式列出，源码中存在 POST /runs/{run_id}/finish。
  • /metric-definitions 与 /primary-metric：设计稿已列出，但源码还包含 PATCH /metric-definitions/{name}。
  • /evaluations 独立列表：源码存在 GET /evaluations 与 GET /evaluations/{eval_id}，设计稿未列出。
  • /runs/{run_id}/events：源码存在该 SDK 上报端点，设计稿事件表格只列出 /events 列表与 SSE。