7.9 KiB
Raw Blame History

API Reference

REST API

Base path: /api

Health and Dashboard

  • GET /api/health: service health check
  • GET /api/ai/status: returns whether server-side AI generation is enabled and which model is configured
  • POST /api/ai/operators/generate: generate a custom operator definition from natural language
  • POST /api/ai/workflows/generate: generate a workflow graph from natural language and the current operator catalog
  • GET /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/projects
  • POST /api/projects
  • GET /api/projects/:id
  • PUT /api/projects/:id
  • DELETE /api/projects/:id
  • GET /api/projects/:id/workflows
  • POST /api/projects/:id/workflows

POST /api/projects

{
  "name": "自动驾驶新项目",
  "description": "处理多摄像头感知数据"
}

Workflows

  • GET /api/workflows/:id
  • PUT /api/workflows/:id
  • DELETE /api/workflows/:id
  • POST /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/templates
  • POST /api/templates
  • GET /api/templates/:id
  • PUT /api/templates/:id
  • DELETE /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/operators
  • POST /api/operators
  • GET /api/operators/:id
  • PUT /api/operators/:id
  • DELETE /api/operators/:id

The reconciled built-in catalog includes the original workflow primitives plus:

  • 目录扫描
  • CSV 转 JSON
  • JSON 转 CSV
  • JSON 字段提取
  • 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/runs
  • GET /api/runs/:id
  • GET /api/runs/:id/logs
  • GET /api/runs/:id/resources
  • GET /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 correctly
  • metadata.mimeType / metadata.sha256: persisted file metadata
  • data: the real JSON payload for JSON artifacts
  • data.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-tasks
  • POST /api/audit-tasks/:id/approve
  • POST /api/audit-tasks/:id/reject

Users and Settings

  • GET /api/users
  • PUT /api/users/:id
  • GET /api/settings
  • PUT /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 default
  • 1+: workflow-specific maximum active runs

Dispatch enforces both the global worker limit and the workflow-specific limit.

  • runTimeoutSeconds
    • 0: disable workflow-level timeout
    • 1+: fail the current run if total execution time exceeds this many seconds
  • nodeTimeoutSeconds
    • 0: disable workflow-level per-node timeout
    • 1+: fail the current node if a single operator execution exceeds this many seconds
  • maxRetryAttempts
    • 0: disable automatic retry
    • 1+: automatically enqueue up to N retry runs after a failed attempt
  • retryBackoffSeconds
    • 0: enqueue retry runs immediately
    • 1+: delay retry dispatch by the configured number of seconds

Run responses may also include:

  • attempt: current attempt number, starting from 1
  • parentRunId: the failed run that spawned this retry run
  • availableAt: 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 check
  • GET /worker-api/stats: current queue/running/audit counts
  • POST /worker-api/process-once: process one queued run immediately
  • POST /worker-api/runs/:id/retry: reset a run to queued and 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 in cmd/api.
  • /worker-api/* is served by the Go worker binary in cmd/worker.
  • Workflow execution and storage models are defined in internal/domain and internal/store.
  • AI generation is implemented by internal/ai and is called only from the Go API, never directly from the browser.
  • GET /api/settings never returns the saved AI key in plaintext. It only exposes ai.hasAPIKey so the browser can show whether a server-side key is already configured.
  • timezone uses IANA timezone identifiers such as Asia/Shanghai or America/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.