Workflows API

GET /workflows — 一覧取得

必要スコープ: workflows:read

クエリパラメータ

レスポンス例

{
  "data": [
    {
      "id": 123,
      "name": "問い合わせ自動共有",
      "description": "Webhook 受信 → AI 要約 → Slack 通知",
      "status": "active",
      "tags": [],
      "is_test_mode": false,
      "created_at": "2026-04-15T10:00:00+09:00",
      "updated_at": "2026-05-01T12:34:56+09:00"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false, "limit": 20 }
}

GET /workflows/{id} — 詳細取得

必要スコープ: workflows:read

ノード構成（flow_data）まで含めた詳細を返します。 UI で編集中のドラフトは含まれず、最後に保存された状態のみが返されます。

GET /workflows/{id}/webhook-info — Webhook URL 取得

必要スコープ: workflows:read

トリガーが Webhook のワークフローについて、起動用 URL と hash を返します。
Webhook 受け口の URL は https://app.pigeon-workflow.ai/api/v1/webhooks/{hash} 形式です。

POST /workflows — 作成

必要スコープ: workflows:write （+ Idempotency-Key 推奨）

POST /api/v1/workflows
X-API-Key: ac_live_...
Idempotency-Key: 7b3a...
Content-Type: application/json

{
  "name": "問い合わせ自動共有",
  "flow_data": { /* ノード・エッジ定義 */ }
}

flow_data のスキーマは管理画面で作成したワークフローを GET でエクスポートして テンプレ化するのが安全です。バリデーションエラー時は 422 + フィールド別エラー詳細が返ります。

PUT /workflows/{id} — 更新

必要スコープ: workflows:write

name・flow_data 等を部分的に更新できます。flow_data を更新すると変更履歴に自動でバージョンが追加されます。

POST /workflows/{id}/execute — 実行

必要スコープ: executions:execute （+ Idempotency-Key 推奨）

POST /api/v1/workflows/123/execute
X-API-Key: ac_live_...
Idempotency-Key: 7b3a...
Content-Type: application/json

{
  "input_data": {
    "customer_name": "山田太郎",
    "company": "株式会社サンプル"
  }
}

→ 202 Accepted
{
  "execution_id": 6821,
  "status": "running",
  "polling_url": "https://app.pigeon-workflow.ai/api/v1/executions/6821",
  "started_at": "2026-05-07T10:00:00+09:00"
}

実行は非同期で開始されます。完了結果は GET /executions/{id} でポーリングするか、 ワークフロー側に Slack 通知 / Webhook 出力ノードを置いて push で受け取るのが推奨です。

DELETE /workflows/{id} — 削除

必要スコープ: workflows:write