37 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: 管理员返回平台概览和供应商对比;supplier_manager只返回其vendor_manager成员关系覆盖的团队指标,其他非管理员只返回本人工作量与质量。默认最近 30 天,from/to最大 366 天。
When DROBOTICFLOW_REQUIRE_SESSION_AUTH=true, AI generation routes require an admin or operator session. Run 列表、详情、日志、资源、通用 artifact 元数据/内容和 lineage 只允许管理员会话;机器 API token 继续用于受控自动化。标注/质检/验收通过 /api/human-items/:id/subject-content 读取经过工作组和阶段角色校验的媒体。
Auth and Organizations
GET /api/public/settings: unauthenticated public settings surface; currently returns onlytimezoneGET /api/auth/bootstrap-status: whether first super-admin bootstrap is requiredPOST /api/auth/bootstrap-super-admin: create the first super adminPOST /api/auth/login: log in with email and password and receive an HttpOnly session cookiePOST /api/auth/logout: revoke the current session cookieGET /api/auth/me: return the current user and organizationGET /api/admin/organizationsPOST /api/admin/organizationsPUT /api/admin/organizations/:idDELETE /api/admin/organizations/:idGET /api/admin/organizations/:id/usersPOST /api/admin/organizations/:id/usersPUT /api/admin/users/:idDELETE /api/admin/users/:idPOST /api/admin/users/:id/reset-password
Session auth uses an HttpOnly droboticflow_session cookie. Existing token-based local deployments remain compatible by default; set DROBOTICFLOW_REQUIRE_SESSION_AUTH=true to require login for business APIs. Unsafe session-authenticated requests, including POST /api/auth/logout, must also send X-Droboticflow-CSRF-Token with the value from the readable droboticflow_csrf cookie. Public LoadBalancer deployments require session auth so business role checks remain active. In session-auth deployments, the shared API token remains valid for admin-monitoring automation and explicitly documented import endpoints; ordinary users cannot use it through the browser and business writes still require a user session with the right role.
POST /api/ai/operators/generate
{
"description": "生成一个算子,用于接收视频输入,抽取关键帧并输出图片列表。"
}
典型响应:
{
"name": "关键帧抽取",
"category": "AI",
"description": "接收视频输入,按固定时间间隔抽取关键帧并输出图片列表与摘要。",
"inputs": [
{ "name": "input", "type": "video", "transmission": "bus", "description": "视频输入或视频 manifest" }
],
"outputs": [
{ "name": "frames", "type": "image", "transmission": "bus", "description": "关键帧图片列表" },
{ "name": "summary", "type": "json", "transmission": "bus", "description": "抽帧摘要" }
],
"hyperparams": [
{ "key": "FRAME_INTERVAL_SECONDS", "value": "5", "description": "按秒抽帧间隔", "type": "string" },
{ "key": "MAX_FRAMES_PER_VIDEO", "value": "50", "description": "单视频最多保留关键帧数", "type": "string" }
],
"skillDefinition": "接收视频文件路径或包含视频路径的 JSON manifest。若路径为 bos://...,先物化到本地工作目录,再按 FRAME_INTERVAL_SECONDS 抽取关键帧,输出图片列表与摘要。"
}
如果你想把这份响应直接转成自定义算子 Markdown,可以把响应保存为本地 JSON 后运行:
python3 scripts/generate_operator_docs.py --input-json /path/to/generated-operator.json
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": "处理多摄像头感知数据"
}
Project names are trimmed and required on create and update. Project status defaults to active; updates accept only active or archived so dashboard counters and project filters stay aligned.
Workflows
GET /api/workflows/:idPUT /api/workflows/:idDELETE /api/workflows/:idPOST /api/workflows/:id/runPOST /api/workflows/:id/releasePOST /api/workflows/:id/versionsGET /api/workflows/:id/capture-automationPUT /api/workflows/:id/capture-automationPOST /api/workflows/:id/capture-automation/records/:recordId/reprocessPOST /api/workflows/:id/capture-automation/records/:recordId/discardPOST /api/workflows/:id/capture-automation/records/:recordId/restore
PUT /api/workflows/:id
{
"name": "视觉处理流程",
"description": "包含扫描、推理、上传",
"type": "batch",
"maxConcurrentRuns": 2,
"nodeTimeoutSeconds": 120,
"runTimeoutSeconds": 300,
"maxRetryAttempts": 1,
"retryBackoffSeconds": 30,
"nodes": [],
"edges": []
}
Workflow names are trimmed and required on create and update. Workflow type accepts only batch or streaming, kind accepts only standard or scan, and workflow status updates accept only draft, ready, running, completed, or failed. Each operator node may optionally set data.sharedMemorySize; when omitted, the worker uses the linked operator resource default and then the platform DROBOTICFLOW_SHARED_MEMORY_SIZE fallback.
PUT /api/workflows/:id/capture-automation 为已发布工作流绑定持续接入目录:
{
"enabled": true,
"connectionId": "storage-fanyu",
"bucket": "drobodata-fanyu",
"prefix": "incoming",
"completionMode": "required_files",
"workflowInputId": "sourceDirectory",
"pollIntervalSeconds": 30,
"maxRetryAttempts": 2,
"retryBackoffSeconds": 60
}
监听器检查 prefix 下的每个一级子目录,不按目录名称筛选。一级目录内必需文件齐全后才创建 Run;平台内部 _droboticflow 目录会被排除。自动重试产生的新 Run 沿用同一 Capture taskId,接口返回的 Capture runId 会指向最新一次尝试。响应计数分别提供 failed 与 cancelled。
Capture 生命周期操作都要求 {"reason":"..."},并把操作者、原因、前后状态、Run 和时间写入 actions:
reprocess:仅允许failed/cancelled,原子切换为requeueing后创建新的retryRun;新 Run 保存parentRunId和递增attempt。重复请求返回409。discard:允许尚未活动的incomplete/ready/failed/cancelled,切换为discarded;监听器保持忽略,但不删除 BOS 源数据。restore:把discarded恢复到放弃前状态;完整性扫描随后决定继续等待还是创建 Run。
cancelled 不参与失败自动重试。用户明确点击 reprocess 才会重新执行;discarded 与 cancelled、failed 分开统计。
人工任务页面和成品包页面在提供 workflowId、runId 时都必须保持精确作用域。GET /api/human-items 已支持两者;GET /api/delivery-packages 的 runId 同时匹配 parentRunId 与 childRunId。前端二级人工 Tab 不得丢弃这些查询参数,默认任务池也不包含历史已通过记录。
POST /api/workflows/:id/run
工作流可通过 workflowInputs 把没有前置边节点的输入端口暴露为运行接口。输入端口支持 required;已发布定义要求根节点必选端口绑定到工作流输入,内部必选端口绑定到上游边。运行请求携带本次具体值:
{
"trigger": "manual",
"inputs": {
"config": { "mode": "inline", "type": "json", "inline": { "threshold": 0.5 } },
"dataset": {
"mode": "ref",
"type": "file",
"ref": {
"provider": "BOS",
"connectionId": "storage-1",
"bucket": "robot-data",
"kind": "directory",
"prefix": "incoming/session-1/",
"manifestKey": "incoming/session-1/manifest.json"
}
}
}
}
inline 仅允许 JSON,序列化后最多 64 KiB;ref 只保存无凭证的对象存储定位和完整性元数据。目录 ref 可以暂不带 manifestKey,Worker 会在根节点启动前列举 prefix 并写入本次 run 的快照 manifest。
工作流定义另有 definitionState: draft | released,不复用会随运行变化的 status。release 完成必选输入和 artifact 存储校验后冻结定义;released 工作流继续接受不同的根输入运行,但 PUT 返回 workflow_definition_locked。POST /api/workflows/:id/versions 从 released 定义创建同族的新草稿版本。
同一 definitionFamilyId 只允许一个当前活动版本出现在项目工作流主列表。POST /api/workflows/:id/activate 将指定的 released 版本设为当前版本,并把同族其他版本标记为隐藏;历史定义、Run 和产物不会删除。GET /api/workflows/:id/versions 按 definitionVersion 倒序返回完整版本历史,包括隐藏版本,供版本历史和回放页面使用。活动版本切换在目标 Run 结束后执行,运行中的版本会返回 workflow_run_active。
{
"trigger": "manual"
}
Scan workflows are created through the same workflow APIs. Their payload can include kind: "scan" and a workflow-level scanConfig object. For BOS scans, scanConfig now supports either inline credentials or a reusable connectionId:
{
"name": "X-platform BOS 扫描",
"type": "streaming",
"kind": "scan",
"schedule": {
"mode": "every_days_at_time",
"dayInterval": 2,
"timeOfDay": "18:30",
"timezone": "Asia/Shanghai"
},
"scanConfig": {
"dataSource": "BOS",
"connectionId": "storage-abc123",
"bucket": "datastorage",
"prefix": "algo/X-platform-test",
"scanMode": "INCREMENTAL",
"enabled": true
},
"nodes": [],
"edges": []
}
When connectionId is present, the workflow stores the reference instead of duplicating AK/SK. The worker and BOS preview API resolve the referenced storage connection at execution time.
Workflow-level schedule now supports three modes:
interval_seconds- uses
interval
- uses
every_hours- uses
intervalHours
- uses
every_days_at_time- uses
dayInterval,timeOfDay, and optionaltimezone
- uses
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. Template names are trimmed and required, template type accepts only batch or streaming, and template kind accepts only standard or scan.
Operators
GET /api/operatorsPOST /api/operatorsGET /api/operators/:idPUT /api/operators/:idDELETE /api/operators/:id
The built-in catalog includes the original workflow primitives plus:
BOS 增量扫描X 平台数据集索引采集目录校验视频质检数据过滤视频切片视频标注成品打包抽检采样目录扫描CSV 转 JSONJSON 转 CSVJSON 字段提取JSON 过滤JSON 映射重命名文本模板渲染条件分流LeRobot 数据集概览ROSBag 数据概览Shell 命令执行
POST /api/operators
{
"name": "自定义分割算子",
"type": "custom",
"category": "AI",
"description": "执行图像分割",
"version": "1.0.0",
"inputs": [{ "id": "in-1", "name": "图像", "type": "image" }],
"outputs": [{ "id": "out-1", "name": "结果", "type": "json" }],
"image": "ccr.example.com/dataflow/custom-seg:latest"
}
POST /api/operators registers custom operators only. Operator names, categories, descriptions, versions, images, image IDs, skill definitions, port IDs, and port names are trimmed before persistence. Operator version defaults to v1 when omitted and must match [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}; use it as the business/runtime version visible to workflow authors. imageId is the digest-pinned image reference when available and defaults to image for directly registered image references. Operator type is immutable after creation and accepts only builtin or custom; registration requires custom. Port type accepts only json, image, video, tensor, or file, and non-empty transmission accepts only bus, oss, shm, or stream. Operator CPU/MEM/sharedMemorySize resource values must be positive Kubernetes resource quantities when present, and GPU must be a positive integer when present. sharedMemorySize controls the writable /dev/shm memory volume for newly created Jobs; a workflow node value overrides the operator default, and an empty value inherits the platform DROBOTICFLOW_SHARED_MEMORY_SIZE default.
POST /api/operators/image-archives/import
Multipart upload endpoint for a pre-built Docker/OCI image archive. The API stores the archive on the shared workspace PVC, starts a Kubernetes import Job using CUSTOM_OPERATOR_IMAGE_IMPORTER_IMAGE, pushes the image to CUSTOM_OPERATOR_IMAGE_REGISTRY, reads the pushed digest, and creates a custom operator whose image and imageId are pinned to repo@sha256:....
Form fields:
file: required.tar,.tar.gz, or.tgzimage archive fromdocker saveor an OCI archive tool.archiveFormat: optional,dockerby default; acceptsdockeroroci.name,type,category,description,version,inputs,outputs,configSchema,hyperparams,resources,skillDefinition: same operator metadata asPOST /api/operators; JSON fields are passed as JSON strings. Whenversionis omitted, it defaults to the final importtag.repository: optional repository suffix underCUSTOM_OPERATOR_IMAGE_REGISTRY; defaults to a sanitized operator name.tag: optional tag; defaults to an import timestamp.
Example:
curl -X POST "$API_BASE/api/operators/image-archives/import" \
-F 'file=@custom-operator.tar' \
-F 'archiveFormat=docker' \
-F 'name=自定义分割算子' \
-F 'type=custom' \
-F 'category=AI' \
-F 'description=执行图像分割' \
-F 'version=1.0.0' \
-F 'outputs=[{"id":"out-1","name":"结果","type":"json"}]'
The response includes version, image for the pushed tag, imageId for the digest-pinned reference, digest, job, and the created operator.
Runs and Monitoring
GET /api/runsGET /api/runs/:idGET /api/workflows/:id/runsPOST /api/runs/:id/rerun-subtreeGET /api/runs/:id/logsGET /api/runs/:id/resourcesGET /api/runs/:id/artifactsGET /api/runs/:id/artifacts/:artifactId/contentGET /api/runs/:id/lineageGET /api/artifacts/:artifactId/lineage
GET /api/runs/:id/logs, GET /api/runs/:id/resources, and GET /api/runs/:id/artifacts accept optional limit and offset query parameters. skip is accepted as an alias for offset. Empty values use defaults, explicit limit values must be positive integers, explicit offset / skip values must be non-negative integers, and oversized limits are capped by the API. Invalid explicit pagination returns 400 instead of falling back to a different page. Logs and resource samples default to the latest 1000 items when the run contains a large history; artifacts default from the start. The response includes:
{
"items": [],
"total": 1200,
"limit": 1000,
"offset": 200,
"truncated": true
}
Resource samples include timestamp, cpu, and memory. When NVIDIA GPU metrics are available, samples may also include gpu, gpuMemoryUsedMiB, gpuMemoryTotalMiB, gpuName, and gpuCount.
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/code, CSV/TSV, JSONL, image thumbnails, audio/video metadata, PDF hints, 3D asset metadata, model/checkpoint metadata, SQLite/ROSBag/MCAP summaries, HDF5/Zarr/Parquet dataset summaries, archives, and LeRobot dataset summaries
When data.dataRef.payloadPath points to a local file, data-asset endpoints treat that file as authoritative external JSON object data. Unreadable, malformed, or non-object payloads are omitted instead of falling back to stale inline data. Data-asset integer summaries such as item counts, byte sizes, and frame counts must be exact integer values; lossy numeric values are ignored rather than truncated.
GET /api/runs/:id/artifacts/:artifactId/content
Streams the selected artifact content for authenticated users with access to the run. Media previews returned by run and artifact APIs use this endpoint instead of embedding video/audio/image bytes as data:*;base64 in JSON responses. The endpoint supports GET and HEAD, browser Range requests, 206 Partial Content, Content-Range, Accept-Ranges, and stable Content-Type detection from artifact metadata or file extension. It serves persisted local artifact files when they still exist, redirects HTTP(S) preview URLs with 307 Temporary Redirect, and can still decode older persisted data-URL previews for backward compatibility. For video artifacts, append ?transcode=browser to request a cached browser-compatible MP4 preview generated through the deployed API's ffmpeg path; Monitoring adds this automatically for artifact video previews. Text-like artifacts, including .txt, .md, .log, .py, .js, .ts, .sql, .yaml, .xml, .jsonl, .obj, .mtl, .gltf, .urdf, .mjcf, .usd, and .usda, can be previewed from this endpoint with a bounded browser Range request. Binary or container formats such as .glb, .stl, .fbx, .onnx, .safetensors, .pt, .pth, .h5, .hdf5, .parquet, .mcap, .bag, .db3, .tfrecord, .zarr, and archives are exposed as typed file previews with download/open actions. For model and 3D asset delivery, append ?download=1 to force Content-Disposition: attachment, preserving the artifact filename for files such as vla-policy-model.json, .onnx, .safetensors, .obj, .mtl, .gltf, .glb, .urdf, and .xml.
GET /api/runs/:id/lineage
Returns execution-level operator and data lineage for a run. Each node includes the operator snapshot used by that execution (operatorId, operatorVersion, operatorImage, operatorImageId), the input artifact snapshot consumed by the node, output artifacts, data references, and the stage manifest path when present. New executions also persist inputLineage, so edges can include the exact workflow edge id plus source and target handles used at runtime. Older runs without inputLineage fall back to persisted inputArtifacts, so they still represent observed artifact flow but may not include target-port details.
GET /api/artifacts/:artifactId/lineage
Returns the artifact-focused lineage and impact view. Pass runId=<run-id> when the caller knows the owning run; otherwise the API searches runs visible to the current tenant. The response includes the artifact snapshot, producing node when known, consuming nodes, upstream edges into the producer, downstream edges from the artifact to consumers, and the reduced related node/edge graph. This endpoint is intended for audit and impact analysis when a reviewer starts from one output artifact instead of the whole run.
POST /api/runs/:id/rerun-subtree
- body:
{ "nodeId": "<workflow-node-id>" } - only allowed on failed runs
- creates a queued child run with:
trigger = rerun_subtreeparentRunId = source failed run idrestartFromNodeId = selected node id
- the child run reuses completed upstream baseline executions and re-executes the selected node plus its downstream subtree
Data Platform
GET /api/scan-projectGET /api/scan-configsPOST /api/scan-configsGET /api/scan-configs/:idPUT /api/scan-configs/:idDELETE /api/scan-configs/:idPOST /api/scan-configs/:id/runGET /api/source-data/collectionsGET /api/source-data/collections/:runId/:collectionIdGET /api/source-data/collections/:runId/:collectionId/entries?prefix=<dir>GET /api/packagesGET /api/packages/:runId/:packageNameGET /api/sampling-tasksGET /api/sampling-tasks/:idPOST /api/sampling-items/:id/review
POST /api/scan-configs
{
"name": "X-platform-test 自采数据扫描",
"description": "扫描并索引真实采集目录",
"sourcePath": "bos://<bucket>/<prefix>",
"bucket": "<bucket>",
"prefix": "<prefix>",
"pattern": "",
"interval": 86400,
"enabled": true,
"dataSource": "BOS"
}
Scan configs are implemented as real workflows under the system project 数据源扫描, not as a second execution engine. For BOS-backed pipelines the first node now uses the built-in BOS 增量扫描 source operator, which persists checkpoint state per workflowId + nodeId + sourceFingerprint. The worker only commits that checkpoint after the whole run succeeds, so downstream failures do not silently skip data on the next retry. GET /api/scan-project resolves the system project for UI redirects, POST /api/scan-configs/:id/run enqueues a normal run, and GET /api/source-data/collections returns data from any completed workflow that produced a real dataset-index.json artifact.
For BOS-backed X-platform scans, source collections are inferred from real meta.json roots inside the scanned prefix. collectionId is a URL-safe stable slug for routing, collectionName is the human-readable leaf folder name such as BJ_001_0001_OsmoNano_2026-03-19_14-51-43, and relativePath preserves the full BOS-relative directory such as raw/BJ_001_0001_OsmoNano_2026-03-19_14-51-43. The frontend groups these source collections together with completed package outputs inside a single 数据资产 module, and drives project/workflow scoping via query filters instead of separate first-level menus.
GET /api/packages
Returns finished data packages aggregated from real packages-manifest.json run artifacts. Each item includes the source projectId, workflowId, runId, package metadata, embedded quality / annotation summaries, and a previewArtifact when a previewable file such as the clip video exists.
GET /api/sampling-tasks
Sampling tasks are synced from real audit-samples.json run artifacts. The API persists review state separately from the originating run so reviewers can submit decisions later without mutating the original workflow outputs. Synced rule summaries must match the runtime rule contract: non-empty unique id, non-empty field, supported comparison operator, and finite numeric (0, 100] samplePercent; malformed rules, boolean percentages, and non-numeric percentages are skipped instead of being persisted as review tasks.
Audit
GET /api/audit-tasksPOST /api/audit-tasks/:id/approvePOST /api/audit-tasks/:id/reject
Users and Settings
GET /api/usersPOST /api/usersPUT /api/users/mePUT /api/users/:idDELETE /api/users/:idGET /api/storage/connectionsPOST /api/storage/connectionsGET /api/storage/connections/:idPUT /api/storage/connections/:idDELETE /api/storage/connections/:idGET /api/external/business-db/tokensPOST /api/external/business-db/tokensPUT /api/external/business-db/tokens/:idPOST /api/external/business-db/tokens/:id/rotateDELETE /api/external/business-db/tokens/:idGET /api/settingsPUT /api/settings
When DROBOTICFLOW_REQUIRE_SESSION_AUTH=true, management reads and writes match the sidebar role model: /api/users, /api/settings, database browser routes, object-storage management routes, and /api/external/business-db/tokens are admin-only. POST /api/users must include a non-blank initial password in session-auth deployments so created users can log in immediately, any password explicitly supplied to a user update must also be non-blank, user names cannot be blank, and account status accepts only active or disabled. Project mutations also reject blank names and unknown project statuses; project status accepts only active or archived. Workflow and template mutations reject blank names and unknown metadata enum values before persistence. Operator mutations reject blank metadata, unknown operator/port enum values, duplicate port IDs, and invalid resource defaults before persistence. Operators and auditors can still update their own profile through PUT /api/users/me, which accepts only name and email and never changes role, status, password, or organization. User storage-path favorites are self-or-admin scoped. The reusable storage and Mongo connection list/get endpoints require admin/operator role so workflow editors can select existing connections without exposing connection metadata to auditors; creating, updating, deleting, and testing connections requires admin.
POST /api/storage/connections
{
"name": "BOS 主连接",
"description": "X-platform 扫描使用",
"provider": "BOS",
"endpoint": "",
"accessKeyId": "ak-...",
"secretAccessKey": "sk-..."
}
GET /api/storage/connections
The response never returns plaintext AK/SK. It only exposes hasAccessKeyId, hasSecretAccessKey, and masked previews so the UI can confirm a real secret is already stored.
GET /api/settings
{
"id": "system",
"k8s": {
"enabled": true,
"endpoint": "https://<api-server>:6443",
"namespace": "droboticflow",
"hasKubeconfig": true
},
"worker": {
"pollIntervalMs": 2000,
"maxConcurrentRuns": 2
},
"ai": {
"provider": "openai-compatible",
"baseURL": "https://ai.example/v1",
"model": "model-x",
"hasAPIKey": true
},
"timezone": "Asia/Shanghai"
}
GET /api/public/settings
{
"timezone": "Asia/Shanghai"
}
PUT /api/settings
{
"timezone": "Asia/Shanghai",
"worker": {
"maxConcurrentRuns": 2
},
"ai": {
"provider": "openai-compatible",
"baseURL": "https://ai.example/v1",
"model": "model-x",
"apiKey": "sk-..."
}
}
Settings updates validate runtime defaults before persistence. worker.pollIntervalMs and worker.maxConcurrentRuns must be positive integers when present. ai.baseURL must be an absolute http(s) URL when present; if ai.apiKey is configured, both ai.baseURL and ai.model are required. defaults.cpuRequest, defaults.cpuLimit, defaults.memoryRequest, and defaults.memoryLimit are trimmed and must be valid positive Kubernetes resource quantities when present. defaults.gpuLimit is optional, but any explicit value must be a positive integer.
Database Browser
GET /api/databaseGET /api/database/collections/:name/documentsGET /api/database/collections/:name/indexes- Business Mongo write endpoints under
/api/database/collections/*
All database browser routes are admin-only when session auth is required. The external partner write API below stays separate and only accepts scoped API keys generated by an admin.
Document browsing accepts optional limit and skip query parameters. Empty values use defaults, explicit limit values must be positive integers, explicit skip values must be non-negative integers, and oversized values are capped by the API before hitting MongoDB or the in-memory store.
External Business DB Write API
For a copy-paste-ready partner handoff guide, see docs/external-business-db-write-api-integration.md.
Use this surface when a third party needs to write into a preconfigured business Mongo connection without seeing the raw Mongo URI. The external caller must use a server-generated API key in header X-API-Key.
Internal token-management routes:
GET /api/external/business-db/tokensPOST /api/external/business-db/tokensPUT /api/external/business-db/tokens/:idPOST /api/external/business-db/tokens/:id/rotateDELETE /api/external/business-db/tokens/:id
Internal token-management routes are admin-only when session auth is required.
POST /api/external/business-db/tokens
{
"name": "partner-a",
"description": "订单同步写入",
"enabled": true,
"scopes": [
{
"connectionId": "mongo_abc123",
"collections": ["orders", "customers"]
}
]
}
Successful create and rotate responses return the plaintext apiKey once. The server stores only the key hash and preview, so callers must save the key from the create or rotate response:
{
"token": {
"id": "exttoken_abc123",
"name": "partner-a",
"enabled": true,
"tokenPreview": "dbw_****7f3a",
"scopes": [
{
"connectionId": "mongo_abc123",
"collections": ["customers", "orders"]
}
]
},
"apiKey": "dbw_9f..."
}
Third-party write routes:
POST /api/external/business-db/documentsPATCH /api/external/business-db/documents/:documentIdPOST /api/external/business-db/upserts
All of these routes require header:
X-API-Key: dbw_...
POST /api/external/business-db/documents
{
"connectionId": "mongo_abc123",
"collection": "orders",
"document": {
"externalId": "EXT-1001",
"status": "new",
"amount": 20
}
}
PATCH /api/external/business-db/documents/:documentId
{
"connectionId": "mongo_abc123",
"collection": "orders",
"patch": {
"status": "done",
"amount": 25
}
}
POST /api/external/business-db/upserts
{
"connectionId": "mongo_abc123",
"collection": "orders",
"match": {
"externalId": "EXT-1001"
},
"patch": {
"status": "done",
"amount": 25
},
"setOnInsert": {
"source": "partner-a"
}
}
External write responses use:
operation: "created"for inserts and create-path upsertsoperation: "updated"for patch and update-path upserts
External write validation intentionally does not expose raw Mongo update operators. document, patch, match, and setOnInsert must all be plain JSON objects.
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>GET /api/object-storageGET /api/object-storage/objectsGET /api/object-storage/contentPOST /api/object-storage/bucketsDELETE /api/object-storage/buckets/:namePOST /api/object-storage/objectsPOST /api/object-storage/objects/uploadPOST /api/object-storage/uploads/presign-putPOST /api/object-storage/uploads/batch/preparePOST /api/object-storage/uploads/multipart/initiatePOST /api/object-storage/uploads/multipart/part-urlPOST /api/object-storage/uploads/multipart/completePOST /api/object-storage/uploads/multipart/abortPATCH /api/object-storage/objectsDELETE /api/object-storage/objects
/api/storage/buckets and /api/storage/objects are workflow-editor browse helpers for selecting real BOS paths from a source path or reusable connection. They require admin/operator role when session auth is required. /api/object-storage* is the object-storage management surface and is admin-only when session auth is required.
GET and HEAD /api/object-storage/content support browser byte-range preview requests. When a request sends a single Range: bytes=<start>-<end> header, the API proxies a ranged BOS read and returns 206 Partial Content, Content-Range, Accept-Ranges: bytes, and a bounded Content-Length without reading the full object into API memory. Video preview components request only metadata up front and add ?transcode=browser for browser-compatible MP4 previews when needed.
POST /api/object-storage/uploads/batch/prepare?connectionId=<id> prepares up to 5000 directory-upload entries before the browser transfers bytes. The payload contains bucket, optional prefix, conflictPolicy (overwrite, skip, or error), and items with relativePath, kind, sizeBytes, and contentType. Relative paths are normalized and traversal segments are rejected. File entries resolve to their destination key; directory entries resolve to <path>/.keep. The response gives each item an upload, create_placeholder, skip, or conflict action plus aggregate counts. The browser then reuses the existing presigned single-file or multipart upload path with four-file concurrency, so the API does not proxy directory file bodies.
BOS may encode an object-missing HEAD response as either NoSuchKey or a generic HTTP 404 NotFound; both are treated as an absent destination during batch preparation. Successful writes retry their immediate metadata lookup briefly so transient post-write visibility does not turn a completed direct, multipart, copy, or rename operation into a false upload failure. Explicit NoSuchBucket responses remain errors.
Worker API
Base path: /worker-api
GET /worker-api/health: worker health checkGET /worker-api/stats: current queue/running/audit countsGET /worker-api/metrics: Prometheus text metrics for queue depth, dispatch counts, node execution counts, cumulative durations, and duration histogramsPOST /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 or invalid external API key returns
401 - authenticated external token without the requested connection or collection permission returns
403 - 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 temporary 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.