STEPLP

仕様・API

管理API v0.1

Workspace/LP・メディア・集計・AI。

管理API v0.1（Swipe LP）

対象: 制作・運用がサーバ側トークンで呼ぶ FastAPI /v1/manage/*。
正本（公開ランタイム） は引き続き api-v0.1.md の GET/POST を参照。

関連: stack.md、lp-definition-v0.1.md。

認証

方式用途
ユーザー JWT（推奨）管理UIログイン後の Authorization: Bearer …。ワークスペースごとに owner / editor / viewer ACL。
X-Admin-Token / Bearer（ADMIN_TOKEN）CI・ブートストラップ・緊急用。本番の日常操作は JWT を正とする。

未設定・不一致は 401。ワークスペース権限不足は 403。

エラー形式

失敗時は次の形を推奨（api-v0.1.md と同系）。

{
  "detail": {
    "error": {
      "code": "not_found",
      "message": "…"
    }
  }
}

エンドポイント一覧

メソッドパス内容
POST/v1/manage/workspacesWorkspace 作成 { name, slug }
GET/v1/manage/workspaces一覧
POST/v1/manage/workspaces/{ws}/landing-pagesLP 作成（public_id は ULID 自動、初回定義は steps 1件以上）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/duplicateLP 複製（定義コピー・新 public_id・下書き。計測キー・公開状態は引き継がない）
GET/v1/manage/workspaces/{ws}/landing-pagesLP 一覧
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/assetsメディアアップロード（multipart/form-data、フィールド名 file）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/creator-knowledge/analyze-reference-urls参考URL解析（自社公開LPは定義取得、外部はスクショ+Vision。結果を referenceAnalyses に保存）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobsAI 画像ジョブ作成（OpenAI gpt-image-2。詳細は ai-lp-image-jobs-v0.1.md）
GET/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobs/{job_id}AI 画像ジョブ取得（ポーリング用）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/writing-suggestionsAI 文案提案（同期・互換。詳細は ai-writing-v0.1.md）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/writing-jobsAI 文案ジョブ作成（非同期。推奨）
GET/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/writing-jobs/{job_id}AI 文案ジョブ取得（ポーリング用）
PATCH/v1/manage/workspaces/{ws}/landing-pages/{lp}definition 更新（definition.id は変更不可）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/preview-share仮公開（いまの definition をサーバにスナップショットし共有トークン発行。本番「公開」とは別）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/publish公開
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/unpublish非公開（published=false。公開 API・埋め込みは 410。下書き definition は残る。live 計測キーは無効化）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/keys計測キー発行 { environment: "live" | "test" }
GET/v1/manage/workspaces/{ws}/landing-pages/{lp}/analytics/summary集計（analytics_batches を走査したLP単位サマリー）

POST .../landing-pages/{lp}/preview-share

編集画面の いまの definition をサーバに保存し、共有用トークン（既定 約7日 で失効）を返す。トークンを知っている人は 認証なし で GET /v1/public/lp-preview/{token}（api-v0.1.md）により同じ形の JSON を取得できる。同一LPで再発行すると 以前のトークンは失効（行を置き換え）。

リクエスト 201

  • ボディ: { "definition": { ... } }（PATCH と同様に definition.id は当該LPの public_id と一致必須）

レスポンス 201

フィールド説明
tokenURLセーフなランダム文字列
expires_at失効時刻（ISO8601）
share_pathWeb のパス（例 /preview/share/{token}）。先頭にサイトオリジンを付けて共有

GET .../landing-pages/{lp}/analytics/summary

POST /v1/analytics/events で取り込んだバッチ（および正規化イベントテーブルがあればそちらを優先）を その場で集計 し、MVPダッシュボード指標のたたき台を返す。

クエリ

パラメータ説明
days任意。直近 N 日に限定（例: 7, 30, 90）。省略時は全期間。
revision任意。特定 revision のイベントのみ（比較用）。

レスポンス 200（LpAnalyticsSummaryOut）

フィールド説明
public_idLP の公開ID
batches_ingested取り込みバッチ件数
unique_sessionslp_view に現れた ユニーク sessionId 数（到達セッションの目安）
events_totalイベント総数
by_event_nameイベント名 → 件数
stepsステップ別: step_views、unique_sessions（当該ステップ到達のユニーク sessionId）、reach_rate_pct（到達セッション比%）、滞在（合計ms・回数・平均ms）
cta_clicks / hotspot_clicks件数
swipe_next_count / swipe_prev_countスワイプイベント件数
engagement_sessions / engagement_rate_pctCTA または HS をタップしたユニーク sessionId 数と到達セッション比（%）
last_event_at取り込み済みイベントの最終 occurredAt（ISO8601 UTC）

注意: バッチ数が多いと遅くなる可能性がある。本番では集計テーブル化・ジョブ分割などの最適化を検討する。

POST .../landing-pages/{lp}/assets

LP に紐づく画像・動画を S3互換バケット に保存し、ブラウザから参照可能な公開URL を返す。管理UIのビジュアル編集から media.src にそのURLを設定する想定。

リクエスト

  • Content-Type: multipart/form-data
  • フィールド名: file（1ファイル）

制約

項目値
最大サイズ30MB（変更時は実装を正とする）
許可 Content-Typeimage/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm

レスポンス 201

フィールド型説明
object_keystringバケット内キー（例: ws/{workspace_uuid}/lp/{lp_uuid}/{ulid}_name.jpg）
urlstring公開URL。S3_PUBLIC_BASE_URL + / + object_key を組み立てたもの

失敗

HTTP条件
400未対応の MIME
404Workspace / LP が存在しない、または別WorkspaceのLP
413サイズ超過（code: payload_too_large）

オブジェクトストレージ・CORS

  • 開発は MinIO（docker-compose で API から http://minio:9000 に接続）。
  • ブラウザが url を直接読み込むため、バケットに GET/HEAD 用 CORS を付与する（実装は起動時に設定）。
  • ホストから MinIO API に直アクセスする場合は 127.0.0.1:9000 を publish し、S3_PUBLIC_BASE_URL と整合させる（例: http://localhost:9000/swipe-lp-media）。

管理UI（参考）

  • LP 定義編集: ビジュアル編集と JSON 編集の併用。
  • 編集プレビュー: 保存前の JSON を parseDefinition 相当で検証し、閲覧ランタイムでその場表示（計測キーなし）。
  • アップロード: 上記 POST .../assets をサーバアクション経由で呼び、返却 url を media.src（または動画ポスター）に反映。

ソース: docs/spec/manage-api-v0.1.md