文档API 开放平台v1 端点参考

v1 端点完整参考

14 个 v1 端点的请求 / 响应 / cURL 示例 + 端到端调用流。

开放平台 v1 共 14 个端点（工作流 3 个、执行 4 个、审批 5 个、产物 2 个），全部挂载在 /api/v1/* 前缀下。每个端点列出所需 scope、请求格式、响应格式、curl 示例。

通用约定

推荐用 Authorization: Bearer dyk_<id>_<secret>；也接受 X-API-Key Header（写法见「鉴权与速率限制」页）
所有响应是 application/json
错误响应统一为 {"error": "..."}，HTTP 状态码语义见「鉴权与速率限制」页
triggerSource = "open_api"：v1 启动的执行不参与 auto-resume，由调用方负责重试 / 幂等

工作流类

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

列出当前 Token owner 可见的工作流。支持分页：?page=1&size=50（默认 50，最大 200）。

bash

curl https://braidrun.com/api/v1/workflows?page=1&size=20 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

响应：

json

{
  "items": [
    {
      "id": "wf-001",
      "name": "Daily ASA report",
      "ownerId": "u-alice",
      "workflow": [...]
    }
  ],
  "total": 17,
  "page": 1,
  "size": 20
}

GET `/api/v1/workflows/{id}`

Scope: WORKFLOW_READ

读取单个工作流定义（含 share / permission 检查）。

bash

curl https://braidrun.com/api/v1/workflows/wf-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/workflows/{id}/executions`

Scope: WORKFLOW_EXECUTE

启动一个新的执行。请求体支持 inputs 与 enableMonitoring 字段。响应 202 Accepted（执行将异步进行）。

bash

curl -X POST https://braidrun.com/api/v1/workflows/wf-001/executions \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "customer_id": "12345",
      "report_date": "2026-04-30"
    },
    "enableMonitoring": true
  }'

响应（202 Accepted）：

json

{
  "executionId": "exec_a3b9c8...",
  "status": "PENDING",
  "workflowId": "wf-001",
  "startedAt": 1735632891234
}

收到 executionId 后，用 GET /api/v1/executions/{id} 轮询状态。

执行类

GET `/api/v1/executions`

Scope: EXECUTION_READ

分页列出当前 owner 的 executions。可按 ?workflowId= ?status= 过滤。

bash

curl 'https://braidrun.com/api/v1/executions?status=RUNNING&size=10' \
  -H "Authorization: Bearer dyk_<id>_<secret>"

GET `/api/v1/executions/{id}`

Scope: EXECUTION_READ

返回执行的实时状态：status / currentStep / completedSteps / totalSteps / startedAt / completedAt / error / stepResults。

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

响应字段含义：

字段	类型	说明
`status`	string	PENDING / RUNNING / COMPLETED / FAILED / CANCELLED / INTERRUPTED
`currentStep`	string?	当前正在执行的步骤名（已完成的为 null）
`completedSteps / totalSteps`	int	用于进度条
`error`	string?	FAILED 状态下的错误信息
`stepResults`	map	step 名 → StepResult，含每步 status / output / duration

GET `/api/v1/executions/{id}/result`

Scope: EXECUTION_READ

返回完整的 ExecutionResult，含 stepResults + duration + 整体输出。终止状态（COMPLETED/FAILED/CANCELLED）后才有值。

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/result \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/executions/{id}/cancel`

Scope: EXECUTION_CANCEL

取消运行中的执行。如果执行已完成或不存在则返回 404。

bash

curl -X POST https://braidrun.com/api/v1/executions/exec_a3b9c8/cancel \
  -H "Authorization: Bearer dyk_<id>_<secret>"

审批类

执行走到 manual_approval 步骤会暂停并生成一条审批记录。下面 5 个端点都要求 APPROVAL_RESPOND scope：外部系统可以列出待审批、读取审批详情（含可编辑的审批表数据）、批准或拒绝。批准后执行继续；拒绝则执行停止；超过审批配置的 timeout 会自动拒绝。

GET `/api/v1/approvals`

Scope: APPROVAL_RESPOND

列出当前 Token owner 可见的审批记录。可按 ?status= 过滤（如 PENDING）；支持分页 ?page=1&size=20（默认 20，最大 200）。

bash

curl 'https://braidrun.com/api/v1/approvals?status=PENDING&page=1&size=20' \
  -H "Authorization: Bearer dyk_<id>_<secret>"

响应：

json

{
  "approvals": [
    {
      "id": "apr-001",
      "executionId": "exec_a3b9c8...",
      "workflowId": "wf-001",
      "stepName": "review_bid_changes",
      "status": "PENDING",
      "approvalMessage": "42 条出价调整待确认",
      "timeout": 86400,
      "createdAt": 1735632891234,
      "expiresAt": 1735719291234,
      "reviewableGroups": [
        {
          "name": "bid_changes",
          "title": "出价调整",
          "items": [],
          "itemsCount": 42
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20
}

列表端点不返回审批表明细

为控制响应体积，列表端点（含按执行查询）会把 reviewableGroups 里的 items 置为空数组，只保留 itemsCount 行数。需要完整明细时请调用详情端点 GET /api/v1/approvals/{id}。

GET `/api/v1/approvals/{id}`

Scope: APPROVAL_RESPOND

读取单条审批的完整内容：status / stepName / approvalMessage / expiresAt，以及 reviewableGroups 的完整 items（审批表逐行数据与列定义）。

bash

curl https://braidrun.com/api/v1/approvals/apr-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

GET `/api/v1/approvals/execution/{executionId}`

Scope: APPROVAL_RESPOND

按执行查审批：返回该 execution 产生的所有审批记录（items 同样被剥离）。轮询执行状态发现暂停时，用它定位要处理的审批。

bash

curl https://braidrun.com/api/v1/approvals/execution/exec_a3b9c8 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

POST `/api/v1/approvals/{id}/approve`

Scope: APPROVAL_RESPOND

批准并让执行继续。请求体两个字段都可选：comment 是审批意见；editedItems 按分组名提交编辑后的行子集——不传则按原始数据放行，传了则引擎只执行你提交的行（对应审批表「可编辑」能力，如直接改出价再批准）。

bash

curl -X POST https://braidrun.com/api/v1/approvals/apr-001/approve \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "确认执行，两条出价手动下调",
    "editedItems": {
      "bid_changes": [
        {"keyword": "photo editor", "newBid": 0.65},
        {"keyword": "collage maker", "newBid": 0.55}
      ]
    }
  }'

响应为更新后的审批记录（status = APPROVED）。审批不存在或已被处理时返回 404。

POST `/api/v1/approvals/{id}/reject`

Scope: APPROVAL_RESPOND

拒绝审批，执行随之停止，不产生任何线上改动。请求体可选 comment 字段记录拒绝原因。

bash

curl -X POST https://braidrun.com/api/v1/approvals/apr-001/reject \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"comment": "本周预算已用完，先不调整"}'

产物类

GET `/api/v1/executions/{id}/artifacts`

Scope: ARTIFACT_READ

列出该 execution 产生的所有产物（含每步生成的文件、报表、截图等）。

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/artifacts \
  -H "Authorization: Bearer dyk_<id>_<secret>"

响应：

json

{
  "artifacts": [
    {
      "id": "art-001",
      "name": "daily-report.xlsx",
      "path": "executions/exec_a3b9c8/.../daily-report.xlsx",
      "storageKey": "executions/exec_a3b9c8/.../daily-report.xlsx",
      "downloadUrl": "/api/executions/exec_a3b9c8/artifacts/art-001/download",
      "previewable": false
    }
  ],
  "total": 1
}

GET `/api/v1/executions/{id}/artifacts/{aid}`

Scope: ARTIFACT_READ

单个产物的元信息，含 downloadUrl 字段。客户端用 downloadUrl 直接拉取实际文件内容（不通过 v1 端点，免费用配额额度）。

bash

curl https://braidrun.com/api/v1/executions/exec_a3b9c8/artifacts/art-001 \
  -H "Authorization: Bearer dyk_<id>_<secret>"

完整 cURL 流：触发 → 轮询 → 拿产物

bash

# 1. 启动执行
EXEC_ID=$(curl -s -X POST \
  https://braidrun.com/api/v1/workflows/wf-001/executions \
  -H "Authorization: Bearer $DYK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"customer_id": "12345"}}' \
  | jq -r .executionId)

# 2. 轮询直到完成
while true; do
  STATUS=$(curl -s \
    "https://braidrun.com/api/v1/executions/$EXEC_ID" \
    -H "Authorization: Bearer $DYK_TOKEN" \
    | jq -r .status)
  echo "$EXEC_ID: $STATUS"
  case $STATUS in
    COMPLETED|FAILED|CANCELLED) break ;;
  esac
  sleep 5
done

# 3. 拿产物列表
curl -s "https://braidrun.com/api/v1/executions/$EXEC_ID/artifacts" \
  -H "Authorization: Bearer $DYK_TOKEN" | jq .artifacts

未来规划

OpenAPI 3 spec 文件 — 供 Swagger UI / 自动生成 SDK
官方 Python / Node.js / Go SDK
Server-sent events: GET /api/v1/executions/{id}/events 实时推送进度
webhook 事件回调（执行完成时回推）

工作流类

GET /api/v1/workflows

GET /api/v1/workflows/{id}

POST /api/v1/workflows/{id}/executions

执行类

GET /api/v1/executions

GET /api/v1/executions/{id}

GET /api/v1/executions/{id}/result

POST /api/v1/executions/{id}/cancel

审批类

GET /api/v1/approvals

GET /api/v1/approvals/{id}

GET /api/v1/approvals/execution/{executionId}

POST /api/v1/approvals/{id}/approve

POST /api/v1/approvals/{id}/reject

产物类

GET /api/v1/executions/{id}/artifacts

GET /api/v1/executions/{id}/artifacts/{aid}

完整 cURL 流：触发 → 轮询 → 拿产物

未来规划

GET `/api/v1/workflows`

GET `/api/v1/workflows/{id}`

POST `/api/v1/workflows/{id}/executions`

GET `/api/v1/executions`

GET `/api/v1/executions/{id}`

GET `/api/v1/executions/{id}/result`

POST `/api/v1/executions/{id}/cancel`

GET `/api/v1/approvals`

GET `/api/v1/approvals/{id}`

GET `/api/v1/approvals/execution/{executionId}`

POST `/api/v1/approvals/{id}/approve`

POST `/api/v1/approvals/{id}/reject`

GET `/api/v1/executions/{id}/artifacts`

GET `/api/v1/executions/{id}/artifacts/{aid}`