7.9 KiB
API Reference
REST API
Base path: /api
Health and Dashboard
GET /api/health: service health checkGET /api/ai/status: returns whether server-side AI generation is enabled and which model is configuredPOST /api/ai/operators/generate: generate a custom operator definition from natural languagePOST /api/ai/workflows/generate: generate a workflow graph from natural language and the current operator catalogGET /api/dashboard: aggregate counts for projects, operators, jobs, and audits
POST /api/ai/operators/generate
{
"description": "生成一个算子,用于接收视频输入,抽取关键帧并输出图片列表。"
}
POST /api/ai/workflows/generate
{
"description": "从对象存储读取视频,抽帧后调用目标检测算子,再把检测结果回传到对象存储。"
}
Projects
GET /api/projectsPOST /api/projectsGET /api/projects/:idPUT /api/projects/:idDELETE /api/projects/:idGET /api/projects/:id/workflowsPOST /api/projects/:id/workflows
POST /api/projects
{
"name": "自动驾驶新项目",
"description": "处理多摄像头感知数据"
}
Workflows
GET /api/workflows/:idPUT /api/workflows/:idDELETE /api/workflows/:idPOST /api/workflows/:id/run
PUT /api/workflows/:id
{
"name": "视觉处理流程",
"description": "包含扫描、推理、上传",
"type": "batch",
"maxConcurrentRuns": 2,
"nodeTimeoutSeconds": 120,
"runTimeoutSeconds": 300,
"maxRetryAttempts": 1,
"retryBackoffSeconds": 30,
"nodes": [],
"edges": []
}
POST /api/workflows/:id/run
{
"trigger": "manual"
}
Templates
GET /api/templatesPOST /api/templatesGET /api/templates/:idPUT /api/templates/:idDELETE /api/templates/:id
Templates now persist the same workflow-level defaults used by project workflows, including type, schedule, maxConcurrentRuns, nodeTimeoutSeconds, runTimeoutSeconds, maxRetryAttempts, and retryBackoffSeconds.
Operators
GET /api/operatorsPOST /api/operatorsGET /api/operators/:idPUT /api/operators/:idDELETE /api/operators/:id
The reconciled built-in catalog includes the original workflow primitives plus:
目录扫描CSV 转 JSONJSON 转 CSVJSON 字段提取JSON 过滤JSON 映射重命名文本模板渲染条件分流LeRobot 数据集概览ROSBag 数据概览Shell 命令执行
POST /api/operators
{
"name": "自定义分割算子",
"type": "custom",
"category": "AI",
"description": "执行图像分割",
"inputs": [{ "id": "in-1", "name": "图像", "type": "image" }],
"outputs": [{ "id": "out-1", "name": "结果", "type": "json" }],
"image": "ccr.example.com/dataflow/custom-seg:latest"
}
Runs and Monitoring
GET /api/runsGET /api/runs/:idGET /api/runs/:id/logsGET /api/runs/:id/resourcesGET /api/runs/:id/artifacts
GET /api/runs/:id/artifacts
Each artifact item can now include:
portId/portName: the originating output port so downstream edges can route multi-output operators correctlymetadata.mimeType/metadata.sha256: persisted file metadatadata: the real JSON payload for JSON artifactsdata.preview: a compact preview object for non-JSON artifacts such as text, CSV/TSV, JSONL, image thumbnails, audio/video metadata, PDF hints, SQLite/rosbag summaries, and LeRobot dataset summaries
Audit
GET /api/audit-tasksPOST /api/audit-tasks/:id/approvePOST /api/audit-tasks/:id/reject
Users and Settings
GET /api/usersPUT /api/users/:idGET /api/settingsPUT /api/settings
GET /api/settings
{
"id": "system",
"k8s": {
"enabled": true,
"endpoint": "https://120.48.161.230:6443",
"namespace": "droboticflow",
"hasKubeconfig": true
},
"worker": {
"pollIntervalMs": 2000,
"maxConcurrentRuns": 2
},
"ai": {
"provider": "dashscope-openai-compatible",
"baseURL": "https://coding.dashscope.aliyuncs.com/v1",
"model": "glm-5",
"hasAPIKey": true
},
"timezone": "Asia/Shanghai"
}
PUT /api/settings
{
"timezone": "Asia/Shanghai",
"worker": {
"maxConcurrentRuns": 2
},
"ai": {
"provider": "dashscope-openai-compatible",
"baseURL": "https://coding.dashscope.aliyuncs.com/v1",
"model": "glm-5",
"apiKey": "sk-..."
}
}
Workflow create/update payloads also accept workflow-level execution settings:
0: inherit the global worker default1+: workflow-specific maximum active runs
Dispatch enforces both the global worker limit and the workflow-specific limit.
runTimeoutSeconds0: disable workflow-level timeout1+: fail the current run if total execution time exceeds this many seconds
nodeTimeoutSeconds0: disable workflow-level per-node timeout1+: fail the current node if a single operator execution exceeds this many seconds
maxRetryAttempts0: disable automatic retry1+: automatically enqueue up to N retry runs after a failed attempt
retryBackoffSeconds0: enqueue retry runs immediately1+: delay retry dispatch by the configured number of seconds
Run responses may also include:
attempt: current attempt number, starting from1parentRunId: the failed run that spawned this retry runavailableAt: when this queued run becomes eligible for dispatch; retry backoff uses this field
Storage
GET /api/storage/buckets?sourcePath=<node SOURCE_PATH>GET /api/storage/objects?sourcePath=<node SOURCE_PATH>&bucket=<bucket>&prefix=<prefix>
Worker API
Base path: /worker-api
GET /worker-api/health: worker health checkGET /worker-api/stats: current queue/running/audit countsPOST /worker-api/process-once: process one queued run immediatelyPOST /worker-api/runs/:id/retry: reset a run toqueuedand clear prior execution state
Response Shape Notes
- list endpoints return
{ "items": [...] } - delete endpoints return
204 No Content - validation failures return
400 - missing resources return
404 - AI service unavailable returns
503 - upstream AI gateway failures return
502 - unhandled server errors return
500
Implementation Notes
/api/*is served by the Go API binary incmd/api./worker-api/*is served by the Go worker binary incmd/worker.- Workflow execution and storage models are defined in
internal/domainandinternal/store. - AI generation is implemented by
internal/aiand is called only from the Go API, never directly from the browser. GET /api/settingsnever returns the saved AI key in plaintext. It only exposesai.hasAPIKeyso the browser can show whether a server-side key is already configured.timezoneuses IANA timezone identifiers such asAsia/ShanghaiorAmerica/Los_Angeles. The frontend formats timestamps with second precision in that timezone.- Monitoring previews are rendered from the persisted artifact payload itself, so text/table/robotics previews keep working after the Kubernetes Job has exited and its local filesystem is gone.
- OSS 相关配置不通过
/api/settings管理。系统设置页只维护 K8s、worker、AI 和默认资源;OSS bucket/prefix 等参数由具体工作流节点维护。 /api/storage/*也不再读取系统级存储根目录。浏览请求必须显式传入当前 OSS 节点超参里的SOURCE_PATH,API 只在这个节点上下文内列 bucket 和对象。- Kubernetes Jobs launched for operator nodes use the Python entrypoint at
backend/operator-runner/main.py.