API リファレンス：シナリオ

シナリオ（scenarios）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。

AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。

GET /api/v1/campaigns/{campaign_id}/scenarios

キャンペーンのシナリオの一覧

operationId：listCampaignScenarios　必要なスコープ：scenarios:read

パラメータ

名前場所型必須説明
campaign_idパスstring（uuid）必須—

応答

ステータス説明型
200成功ScenarioListOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

POST /api/v1/campaigns/{campaign_id}/scenarios

シナリオの作成

operationId：createCampaignScenario　必要なスコープ：scenarios:write

パラメータ

名前場所型必須説明
campaign_idパスstring（uuid）必須—

リクエストの本文（JSON）

型：ScenarioIn（必須）

項目型必須説明
namestring必須—
statusstring（null 可）—作成時は常に draft。APIキーは draft 以外を指定すると 422 値：draft・active・paused（今後増えることがある）
abandon_wait_minutesinteger（null 可）——

応答

ステータス説明型
201成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
409状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

GET /api/v1/scenarios/{scenario_id}

シナリオの取得

operationId：getScenario　必要なスコープ：scenarios:read

パラメータ

名前場所型必須説明
scenario_idパスstring（uuid）必須—

応答

ステータス説明型
200成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

PATCH /api/v1/scenarios/{scenario_id}

シナリオの更新

operationId：updateScenario　必要なスコープ：scenarios:write

status: active は検証を全部通った時だけ（理由は 422 の message・先頭の param）。

パラメータ

名前場所型必須説明
scenario_idパスstring（uuid）必須—

リクエストの本文（JSON）

型：ScenarioPatch（必須）

項目型必須説明
namestring（null 可）——
statusstring（null 可）—値：draft・active・paused（今後増えることがある）
abandon_wait_minutesinteger（null 可）——

応答

ステータス説明型
200成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

DELETE /api/v1/scenarios/{scenario_id}

シナリオの削除

operationId：deleteScenario　必要なスコープ：scenarios:write

パラメータ

名前場所型必須説明
scenario_idパスstring（uuid）必須—

応答

ステータス説明型
204成功（本文なし）—
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
409状態の衝突（invalid_request）。scenario_active（稼働中のシナリオ）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

PUT /api/v1/scenarios/{scenario_id}/steps

シナリオのステップの置き換え

operationId：replaceScenarioSteps　必要なスコープ：scenarios:write

一括置換。1件でも不正なら 422 で全体を保存しない。

パラメータ

名前場所型必須説明
scenario_idパスstring（uuid）必須—

リクエストの本文（JSON）

型：StepsIn（必須）

項目型必須説明
stepsStepIn の配列必須—

応答

ステータス説明型
200成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

GET /api/v1/scenario_presets

シナリオのテンプレートの一覧

operationId：listScenarioPresets　必要なスコープ：scenarios:read

available はテナントの実効上限（1シナリオのステップ数）で決まる。

応答

ステータス説明型
200成功ScenarioPresetListOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

POST /api/v1/campaigns/{campaign_id}/scenarios/from_preset

テンプレートからシナリオを作成

operationId：createCampaignScenarioFromPreset　必要なスコープ：messages:write・scenarios:write（すべて必要）

メッセージも作る＝messages:write も要る。上限超過は 403・途中で失敗したら何も残さない。

パラメータ

名前場所型必須説明
campaign_idパスstring（uuid）必須—

リクエストの本文（JSON）

型：FromPresetIn（必須）

項目型必須説明
preset_keystring必須—
namestring（null 可）——

応答

ステータス説明型
201成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
409状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

POST /api/v1/scenarios/{scenario_id}/duplicate

シナリオの複製

operationId：duplicateScenario　必要なスコープ：messages:write・scenarios:write（すべて必要）

複製。必ず draft で作る。メッセージも実体コピー＝messages:write も要る。

他キャンペーン（同じテナント）へも複製できる。他テナントの指定は 404。

パラメータ

名前場所型必須説明
scenario_idパスstring（uuid）必須—

リクエストの本文（JSON）

型：ScenarioDuplicateIn（必須）

項目型必須説明
campaign_idstring（uuid）（null 可）——
namestring（null 可）——

応答

ステータス説明型
201成功ScenarioOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
409状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error