文件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}`