ドキュメントAPIオープンプラットフォームv1 エンドポイントリファレンス

v1 エンドポイントの完全なリファレンス

14 個の v1 エンドポイントのリクエスト / レスポンス / cURL 例 + エンドツーエンドの呼び出しフロー。

オープンプラットフォーム v1 には全 14 種類のエンドポイント（ワークフロー 3 種、実行 4 種、承認 5 種、成果物 2 種）があり、すべて /api/v1/* プレフィックス配下に配置されています。各エンドポイントには必要な scope、リクエスト形式、レスポンス形式、curl の例が記載されています。

一般規約

Authorization: Bearer dyk_<id>_<secret> の使用を推奨します。X-API-Key ヘッダーも受け付けます（記述方法は「認証とレート制限」ページを参照）
すべてのレスポンスは application/json です
エラー応答は {"error": "..."} として統一されます。 HTTP ステータスコードのセマンティクスについては、「認証とレート制限」ページを参照してください。
triggerSource = "open_api": v1 によって開始された実行は自動再開に参加せず、呼び出し側が再試行/冪等の責任を負います。

ワークフロークラス

GET `/api/v1/workflows`

Scope: WORKFLOW_READ

現在のトークン所有者に表示されるワークフローをリストします。ページングをサポートします:?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

単一のワークフロー定義を読み取ります (共有/権限チェックあり)。

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

新しい実行を開始します。リクエスト本文は、入力フィールドとenableMonitoringフィールドをサポートします。応答 202 受け入れられました (実行は非同期で行われます)。

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 が受け入れられました):

json

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

実行IDを受け取った後、使用します GET /api/v1/executions/{id} 投票ステータス。

実行クラス

GET `/api/v1/executions`

Scope: EXECUTION_READ

現在の所有者の実行のページ分割されたリスト。 ?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/completeSteps/totalSteps/startAt/completeAt/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	ステップ名 → StepResult (各ステップのステータス/出力/期間を含む)

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

Scope: EXECUTION_READ

stepResults + 期間 + 全体的な出力を含む、完全な ExecutionResult を返します。この値は、終了ステータス (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 ステップに到達すると一時停止し、承認レコードが 1 件生成されます。以下の 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

承認して実行を継続させます。リクエストボディの 2 つのフィールドはいずれも任意です。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

この実行によって生成されたすべての製品をリストします (各ステップで生成されたファイル、レポート、スクリーンショットなどを含む)。

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 仕様ファイル — Swagger UI / 自動生成された SDK 用
公式 Python/Node.js/Go SDK
サーバー送信イベント: 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}`