跳转到主要内容
文档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 共存期。