API リファレンス：ポップアップ
ポップアップ（popups）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。
AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。
- GET /api/v1/popups ポップアップの一覧（
listPopups） - POST /api/v1/popups ポップアップの作成（下書き）（
createPopup） - GET /api/v1/popups/{popup_id} ポップアップの取得（
getPopup） - PATCH /api/v1/popups/{popup_id} ポップアップの更新（
updatePopup）
GET /api/v1/popups
ポップアップの一覧
operationId：listPopups 必要なスコープ：popups:read
パラメータ
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
site_id | クエリ | string（uuid）（null 可） | — | — |
limit | クエリ | integer | — | 1〜200・既定値 50 |
cursor | クエリ | string（null 可） | — | — |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 200 | 成功 | PopupListOut |
| 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 / Popup 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/popups
ポップアップの作成（下書き）
operationId：createPopup 必要なスコープ：popups:write
作成した時点で publish まで走る（draft＝KV のキーを消す）。失敗しても 201。
リクエストの本文（JSON）
型：PopupIn（必須）
| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
site_id | string（uuid） | 必須 | — |
name | string | 必須 | — |
kind | string | 必須 | retain（引き止め型）／capture（連絡先取得型） 値：retain・capture（今後増えることがある） |
memo | string（null 可） | — | — |
config | object（項目は未掲載）（null 可） | — | 表示内容・トリガー・表示期間などの設定（項目は今後増える） |
priority | integer（null 可） | — | — |
campaign_id | string（uuid）（null 可） | — | 連絡先取得型の取得先キャンペーン（同じサイト・有効化に必須） |
status | string（null 可） | — | 作成時は常に draft。draft 以外を指定すると 422 値：draft・active・paused（今後増えることがある） |
acknowledgements | string の配列（null 可） | — | 注釈を確認したうえで使う設定の確認（保存されず、監査ログに残る）。timer_end_of_day＝カウントダウンを「当日 23:59 まで」（config.content.timer.mode＝end_of_day）に新しくする保存で必須。back_button＝戻るボタンのトリガー（config.trigger.back_button＝true）に新しくする保存で必須。無ければ 422 acknowledgement_required。APIキーでは新しく設定できない（403 session_required） |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 201 | 成功 | PopupDetailOut |
| 401 | APIキーが無効・失効（authentication_error） | Error |
| 403 | スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等） | Error |
| 404 | site_id のサイト・campaign_id のキャンペーンが見つからない（not_found） | Error |
| 409 | 状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中） | Error |
| 422 | パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語） | Error |
| 429 | レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Popup 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/popups/{popup_id}
ポップアップの取得
operationId：getPopup 必要なスコープ：popups:read
パラメータ
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
popup_id | パス | string（uuid） | 必須 | — |
nonce | クエリ | boolean | — | 既定値 false |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 200 | 成功 | PopupDetailOut |
| 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 / Popup 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/popups/{popup_id}
ポップアップの更新
operationId：updatePopup 必要なスコープ：popups:write
status: active は上限（active の数）と連絡先取得型のキャンペーン指定を通った時だけ。
保存に続けて publish（有効＝値を書く・それ以外＝キーを消す）。失敗しても 200。
パラメータ
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
popup_id | パス | string（uuid） | 必須 | — |
リクエストの本文（JSON）
型：PopupPatch（必須）
| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
name | string（null 可） | — | — |
memo | string（null 可） | — | — |
config | object（項目は未掲載）（null 可） | — | — |
priority | integer（null 可） | — | — |
campaign_id | string（uuid）（null 可） | — | — |
status | string（null 可） | — | active＝有効化・paused＝停止。APIキーは送ると 403 値：draft・active・paused（今後増えることがある） |
acknowledgements | string の配列（null 可） | — | 注釈を確認したうえで使う設定の確認（保存されず、監査ログに残る）。timer_end_of_day＝カウントダウンを「当日 23:59 まで」（config.content.timer.mode＝end_of_day）に新しくする保存で必須。back_button＝戻るボタンのトリガー（config.trigger.back_button＝true）に新しくする保存で必須。無ければ 422 acknowledgement_required。APIキーでは新しく設定できない（403 session_required） |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 200 | 成功 | PopupDetailOut |
| 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）。invalid_status_transition（draft へは戻せない） | Error |
| 422 | パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語） | Error |
| 429 | レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Popup 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する | Error |
| 5XX | サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する） | Error |