跳轉到主要內容
文件API 開放平台概覽
開放平台 · 入門

API 開放平台概覽

開發者：什麼是開放平台、5 分鐘上手、開放範圍、版本承諾。

Braidrun Workflow 開放式平台讓外部系統透過穩定的 REST API 驅動工作流程：觸發執行、讀取結果、推播審核決策、下載產物。所有公開介面由 API Key 識別——同一套機制覆蓋 Webhook、批准回呼與開放平台 v1 端點。

誰應該使用

  • 需要在 CI/CD、內部業務系統、行動 App 服務中觸發工作流程的開發者
  • 從 Slack/Telegram/郵件中點選連結完成審核的營運場景
  • 為合作夥伴提供工作流程即服務（Workflow-as-a-Service）的團隊
  • 需要把執行結果回流到企業資料倉儲 / BI 系統的資料團隊

整體架構

text
┌──────────────────┐    Authorization: Bearer dyk_xxx     ┌──────────────────────┐
│   你的客户端     │ ───────────────────────────────────▶ │  Braidrun Workflow    │
│                  │                                       │   开放平台 v1 / Webhook │
│  - SDK / curl    │ ◀─── 200 OK + JSON ──────────────── │                      │
│  - CI/CD         │ ◀─── 429 + Retry-After ──────────── │  - 校验 scope        │
│  - 邮件链接      │ ◀─── 401 Unauthorized ───────────── │  - 速率限制          │
└──────────────────┘                                       │  - 累计用量          │
                                                            └──────────────────────┘

一次完整的開放平台呼叫：客戶端持有 dyk_<id>_<secret> 形式的 Token，每次請求帶上 Bearer Header；服務端按 scope 校驗後自動累計用量；超過套餐速率上限時返回 HTTP 429 + Retry-After。

5 分鐘上手

  1. 登錄 Braidrun 控制台 → 進入「帳號設定 → API 金鑰」
  2. 建立 API Key 點「新 API Key」→ 選擇所需的 scope（建議先選 WORKFLOW_READ + WORKFLOW_EXECUTE）→ 設定有效期限
  3. 複製 Token 產生成功後會彈出一次性顯示的 Token，立即複製儲存到您的金鑰管理工具
  4. 呼叫一個端點測試 用 curl 拉取自己的工作流列表：
bash
curl https://braidrun.com/api/v1/workflows \
  -H "Authorization: Bearer dyk_<id>_<secret>"

開放範圍

域範圍
Webhook 觸發外部系統 → POST 觸發已綁定的工作流程執行
審核 Webhook從郵件 / Slack / Telegram 一鍵核准/拒絕 manual_approval 步驟
工作流程 v1列出 / 讀取工作流程定義；透過 API 啟動執行
執行 v1查詢執行狀態 / 讀取結果 / 取消執行
審批 v1列出待審批 / 讀取審批詳情 / 批准（可附編輯後的審批表資料）/ 拒絕 manual_approval 步驟
產物 v1列出執行產物 / 拿到產物下載鏈接

查閱指南

版本承諾

v1 是穩定 API 表面：欄位不會被破壞性刪除，新增欄位可加入。重大變更將透過新的 v2 路徑前綴發布，並提供至少 6 個月的 v1 → v2 共存期。