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

> https://okaeri.tech/developers/reference/scenarios/ の Markdown 版。

シナリオ（`scenarios`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/campaigns/{campaign_id}/scenarios](https://okaeri.tech/developers/reference/scenarios.md#listCampaignScenarios)　キャンペーンのシナリオの一覧（`listCampaignScenarios`）
- [POST /api/v1/campaigns/{campaign_id}/scenarios](https://okaeri.tech/developers/reference/scenarios.md#createCampaignScenario)　シナリオの作成（`createCampaignScenario`）
- [GET /api/v1/scenarios/{scenario_id}](https://okaeri.tech/developers/reference/scenarios.md#getScenario)　シナリオの取得（`getScenario`）
- [PATCH /api/v1/scenarios/{scenario_id}](https://okaeri.tech/developers/reference/scenarios.md#updateScenario)　シナリオの更新（`updateScenario`）
- [DELETE /api/v1/scenarios/{scenario_id}](https://okaeri.tech/developers/reference/scenarios.md#deleteScenario)　シナリオの削除（`deleteScenario`）
- [PUT /api/v1/scenarios/{scenario_id}/steps](https://okaeri.tech/developers/reference/scenarios.md#replaceScenarioSteps)　シナリオのステップの置き換え（`replaceScenarioSteps`）
- [GET /api/v1/scenario_presets](https://okaeri.tech/developers/reference/scenarios.md#listScenarioPresets)　シナリオのテンプレートの一覧（`listScenarioPresets`）
- [POST /api/v1/campaigns/{campaign_id}/scenarios/from_preset](https://okaeri.tech/developers/reference/scenarios.md#createCampaignScenarioFromPreset)　テンプレートからシナリオを作成（`createCampaignScenarioFromPreset`）
- [POST /api/v1/scenarios/{scenario_id}/duplicate](https://okaeri.tech/developers/reference/scenarios.md#duplicateScenario)　シナリオの複製（`duplicateScenario`）

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

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

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

### パラメータ

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

### 応答

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

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

**シナリオの作成**

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

### パラメータ

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

### リクエストの本文（JSON）

型：[ScenarioIn](https://okaeri.tech/developers/reference/schemas.md#ScenarioIn)（必須）

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

### 応答

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

## GET /api/v1/scenarios/{scenario_id}

**シナリオの取得**

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

### パラメータ

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

### 応答

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

## PATCH /api/v1/scenarios/{scenario_id}

**シナリオの更新**

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

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

### パラメータ

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

### リクエストの本文（JSON）

型：[ScenarioPatch](https://okaeri.tech/developers/reference/schemas.md#ScenarioPatch)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `name` | `string`（null 可） | — | — |
| `status` | `string`（null 可） | — | 値：`draft`・`active`・`paused`（今後増えることがある） |
| `abandon_wait_minutes` | `integer`（null 可） | — | — |

### 応答

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

## DELETE /api/v1/scenarios/{scenario_id}

**シナリオの削除**

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

### パラメータ

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

### 応答

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

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

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

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

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

### パラメータ

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

### リクエストの本文（JSON）

型：[StepsIn](https://okaeri.tech/developers/reference/schemas.md#StepsIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `steps` | [StepIn](https://okaeri.tech/developers/reference/schemas.md#StepIn) の配列 | 必須 | — |

### 応答

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

## GET /api/v1/scenario_presets

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

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

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

### 応答

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

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `preset_key` | `string` | 必須 | — |
| `name` | `string`（null 可） | — | — |

### 応答

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

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

**シナリオの複製**

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

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

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

### パラメータ

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

### リクエストの本文（JSON）

型：[ScenarioDuplicateIn](https://okaeri.tech/developers/reference/schemas.md#ScenarioDuplicateIn)（必須）

| 項目 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `campaign_id` | `string`（uuid）（null 可） | — | — |
| `name` | `string`（null 可） | — | — |

### 応答

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