本文へスキップ
ホーム/Public API

Public API 概要

3 セクションPublic API v1

ワークフローの管理・実行・履歴取得を、外部システムから REST API 経由で行うためのリファレンスです。 ベース URL は https://app.pigeon-workflow.ai/api/v1、認証は API Key、レート制限は 60 req/min となります。

エンドポイントの基本

ベース 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 ヘッダに付けてリクエストします。

cURLapi-sample.sh
# 自分のアカウント情報を取得
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)

API Key の発行手順、スコープ一覧、Idempotency-Key、運用ベストプラクティスを解説します。

Workflows エンドポイント

ワークフローの一覧取得・作成・更新・削除・実行を行うエンドポイント群のリファレンス。

Executions / Webhooks

実行履歴の取得と、Webhook トリガーによる外部システム連携の API リファレンス。

このページは役に立ちましたか？フィードバックは記事改善に活用させていただきます。