メインコンテンツへスキップ
Public API v1

Public API 概要

ワークフローの管理・実行・履歴取得を、外部システムから REST API 経由で行うためのリファレンスです。

エンドポイントの基本

ベース URL: https://app.pigeon-workflow.ai/api/v1
プロトコル: HTTPS のみ。HTTP からの接続は受け付けません。
レスポンス形式: 全レスポンスは application/json; charset=utf-8。
レート制限: API Key あたり 60 req/min（429 で Retry-After ヘッダ返却）。

提供エンドポイント

メソッドパス必要スコープ用途
GET/me（共通）API Key の所属アカウント情報
GET/workflowsworkflows:readワークフロー一覧
GET/workflows/{id}workflows:readワークフロー詳細
GET/workflows/{id}/webhook-infoworkflows:readWebhook URL/Hash 取得
POST/workflowsworkflows:writeワークフロー作成
PUT/workflows/{id}workflows:writeワークフロー更新
DELETE/workflows/{id}workflows:writeワークフロー削除
POST/workflows/{id}/executeexecutions:executeワークフロー実行
GET/executionsexecutions:read実行履歴一覧
GET/executions/{id}executions:read実行履歴詳細
POST/webhooks/{hash}（不要・hash 認証）Webhook トリガー

最小サンプル

API Key を X-API-Key ヘッダに付けてリクエストします。

# 自分のアカウント情報を取得
curl https://app.pigeon-workflow.ai/api/v1/me \
  -H "X-API-Key: ac_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# ワークフロー一覧
curl https://app.pigeon-workflow.ai/api/v1/workflows \
  -H "X-API-Key: ac_live_..."

# ワークフロー実行（Idempotency-Key 推奨）
curl -X POST https://app.pigeon-workflow.ai/api/v1/workflows/123/execute \
  -H "X-API-Key: ac_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"input_data": {"customer_name": "山田太郎"}}'

エラーハンドリング

HTTP意味対処
400リクエスト形式エラーerror.code / error.message を確認
401API Key 無効・期限切れ管理画面で Key の状態を確認、必要なら rotate
403スコープ不足Key に必要なスコープ（例: workflows:write）を追加
404リソースなし / 別組織ID と所属組織を確認
409Idempotency 競合異なる Idempotency-Key でリトライ
422バリデーションエラーerror.details 配下のフィールド別エラーを修正
429レート制限超過Retry-After ヘッダの秒数だけ待機後にリトライ
5xxサーバーエラー指数バックオフでリトライ。継続する場合はサポートへ連絡

次のステップ

API Key の発行とエンドポイント別の詳細仕様は下記から。