API リファレンス：キャンペーン

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

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

GET /api/v1/campaigns　キャンペーンの一覧（listCampaigns）
POST /api/v1/campaigns　キャンペーンの作成（createCampaign）
GET /api/v1/campaigns/{campaign_id}　キャンペーンの取得（getCampaign）
PATCH /api/v1/campaigns/{campaign_id}　キャンペーンの更新（updateCampaign）
PUT /api/v1/campaigns/{campaign_id}/url-rules　キャンペーンの URL ルールの置き換え（replaceCampaignUrlRules）
PUT /api/v1/campaigns/{campaign_id}/form-profile　キャンペーンのフォーム項目の置き換え（replaceCampaignFormProfile）
POST /api/v1/campaigns/{campaign_id}/duplicate　キャンペーンの複製（duplicateCampaign）

GET /api/v1/campaigns

キャンペーンの一覧

operationId：listCampaigns　必要なスコープ：campaigns:read

パラメータ

名前	場所	型	必須	説明
`site_id`	クエリ	`string`（uuid）（null 可）	—	—
`status`	クエリ	`string`（null 可）	—	値：`active`・`paused`・`archived`（今後増えることがある）
`limit`	クエリ	`integer`	—	1〜200・既定値 `50`
`cursor`	クエリ	`string`（null 可）	—	—

応答

ステータス	説明	型
200	成功	CampaignListOut
401	APIキーが無効・失効（`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

キャンペーンの作成

operationId：createCampaign　必要なスコープ：campaigns:write

作った時点でサイトの設置コードに並ぶ（サイト詳細がキャンペーン別のコードを出す）。

リクエストの本文（JSON）

型：CampaignIn（必須）

項目	型	必須	説明
`site_id`	`string`（uuid）	必須	—
`key`	`string`	必須	—
`name`	`string`	必須	—
`product_name`	`string`（null 可）	—	—
`status`	`string`（null 可）	—	省略時はセッション=active・APIキー=paused。APIキーは paused のみ指定可値：`active`・`paused`・`archived`（今後増えることがある）
`abandon_wait_minutes`	`integer`（null 可）	—	—

応答

ステータス	説明	型
201	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	`site_id` のサイトが見つからない（`not_found`）	Error
409	状態の衝突（`invalid_request`）。`campaign_key_taken`（同じ `key` のキャンペーンがある）／`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/campaigns/{campaign_id}

キャンペーンの取得

operationId：getCampaign　必要なスコープ：campaigns:read

パラメータ

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

応答

ステータス	説明	型
200	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404	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

PATCH /api/v1/campaigns/{campaign_id}

キャンペーンの更新

operationId：updateCampaign　必要なスコープ：campaigns:write

パラメータ

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

リクエストの本文（JSON）

型：CampaignPatch（必須）

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

応答

ステータス	説明	型
200	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404	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/campaigns/{campaign_id}/url-rules

キャンペーンの URL ルールの置き換え

operationId：replaceCampaignUrlRules　必要なスコープ：campaigns:write

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

パラメータ

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

リクエストの本文（JSON）

型：UrlRulesIn（必須）

項目	型	必須	説明
`rules`	UrlRuleIn の配列	必須	—

応答

ステータス	説明	型
200	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404	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/campaigns/{campaign_id}/form-profile

キャンペーンのフォーム項目の置き換え

operationId：replaceCampaignFormProfile　必要なスコープ：campaigns:write

フォーム項目の手動セレクタ。空配列を送ると自動検出へ戻る。

パラメータ

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

リクエストの本文（JSON）

型：FormProfileIn（必須）

項目	型	必須	説明
`tel_selectors`	`string` の配列（null 可）	—	—
`email_selectors`	`string` の配列（null 可）	—	—
`consent_selector`	`string`（null 可）	—	—
`tel_split_selectors`	`string` の配列（null 可）	—	—

応答

ステータス	説明	型
200	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404	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}/duplicate

キャンペーンの複製

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

複製。必ず一度も稼働していない停止中（タグ設定に載らない）で作る。

配下のシナリオ（下書きで）とメッセージ（実体コピー）も作る＝3つの書き込みスコープが要る。

パラメータ

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

リクエストの本文（JSON）

型：CampaignDuplicateIn（必須）

項目	型	必須	説明
`key`	`string`（null 可）	—	—
`name`	`string`（null 可）	—	—

応答

ステータス	説明	型
201	成功	CampaignDetailOut
401	APIキーが無効・失効（`authentication_error`）	Error
403	スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等）	Error
404	対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404	Error
409	状態の衝突（`invalid_request`）。`campaign_key_taken`（同じ `key` のキャンペーンがある）／`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