開発者向けドキュメント

• API・MCP 連携はStarter プラン以上でご利用いただけます（Free プランでは APIキーの発行・外部アプリ接続はできません）。
• APIキーの発行・失効はワークスペースのオーナーのみ行えます。外部アプリ接続（OAuth / MCP）の承認・失効は各メンバーが自分の接続について行えます（オーナーは全メンバーの接続を確認・失効できます）。

1. FormEdge 管理画面にログインし、「設定」→「APIキー」を開きます。
2. キーの名前（用途）を入力して発行します。
3. 発行されたキー（fe_live_...）は作成時に一度だけ表示されます。安全な場所に保管してください。

キーはワークスペース（テナント）に帰属します。漏洩した場合は速やかに失効し、新しいキーを発行してください。

すべてのリクエストで、APIキーを Authorization ヘッダーに Bearer トークンとして指定します。

curl "https://admin-api.formedge.app/api/ext/v1/forms" \
  -H "Authorization: Bearer fe_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

ベース URL は https://admin-api.formedge.app です。

APIキーにはスコープが設定されており、エンドポイントごとに必要なスコープが決まっています。

• read:forms — フォームの一覧・詳細
• read:submissions — 投稿の一覧・詳細・CSV エクスポート
• read:usage — ストレージ使用量
• read:attachments — 添付ファイルの一覧
• read:pages — ページの一覧・詳細、テンプレート・作成ルール
• write:pages — ページの作成・下書き編集（書き込み。既定では付与されず、発行時の明示選択が必要）
• write:forms — フォームの作成・基本情報の更新・フィールド定義の一括置換（書き込み。既定では付与されず、発行時の明示選択が必要）
• read:notifications — 通知設定の参照（宛先・webhook ヘッダ等の機微情報を含むため、read 系では例外的に既定では付与されず、発行時の明示選択が必要）
• write:notifications — 通知設定の全量置換（書き込み。既定では付与されず、発行時の明示選択が必要）
• read:assets — 素材（画像アセット）の一覧（read 系ですが既定では付与されず、発行時の明示選択が必要）
• write:assets — 素材のアップロード（アップロード URL 発行と確定。ストレージを消費するため、既定では付与されず発行時の明示選択が必要）
• read:custom-domains — カスタムドメインの一覧（ページ・フォームの公開先ドメイン設定に使う ID の取得。インフラ設定を露出するため既定では付与されず、発行時の明示選択が必要）
• write:custom-domains — カスタムドメインの登録・再検証・削除（インフラ設定を変更するため、既定では付与されず発行時の明示選択が必要）
• publish:pages — ページの公開・非公開（write:pages とは別の明示選択。下書き作成までを許すキーと公開まで許すキーを分けられます）
• publish:forms — フォームの公開・非公開（publish:pages と同じく発行時の明示選択が必要）

スコープはキー発行時に必要な範囲だけを選択できます（既定は read 系すべて。ただし read:notifications は機微情報を含むため、read:assets とあわせて明示選択・write 系 / publish 系も明示選択）。write 系・publish 系は対応する read 系を自動的に含みます。発行後の変更はできないため、変更する場合は失効して再発行してください。

• 一覧系は page（1 始まり）と per_page で取得し、レスポンスの pagination（page / per_page / total）で総件数を確認できます。
• 期間指定（from / to）は yyyy-MM-dd（日本時間・両端の日を含む）で指定します。
• レスポンスの日時は ISO-8601 形式です。

エラーは RFC 9457 Problem Details（application/problem+json）で返します。

{
  "type": "https://valueforms.jp/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "この API キーには必要なスコープ（read:forms）がありません",
  "instance": "/api/ext/v1/forms"
}

• 401 — APIキーが無効・未指定
• 403 — スコープ不足／プランで API / MCP 連携が利用できない状態（Free へのダウングレード等。アップグレードで既存キーのまま再開できます）／ワークスペースが無効（凍結・解約）／OAuth（MCP）接続が未承認（レスポンスの connect_url が示す承認ページで接続を承認すると解消）
• 404 — 対象が見つからない
• 422 — 入力値エラー（日付書式など）
• 429 — レート制限またはクォータ超過（quota_exceeded が true のときクォータ超過）

APIキーごとに 1 分あたりのリクエスト数に上限があります。429（quota_exceeded=false）が返った場合は、間隔をあけて再試行してください。

公式のリモート MCP（Model Context Protocol）サーバー https://mcp.formedge.app/mcp に接続すると、Claude / Claude Code / Cursor 等の AI エージェントから自然言語でフォーム・ランディングページの作成〜公開までを行えます（中身は本 API の薄いラッパーです）。インストールは不要で、接続時に FormEdge アカウントでサインインして認可します（OAuth）。

Claude Code での登録例:

claude mcp add --transport http formedge https://mcp.formedge.app/mcp

claude.ai の場合は Settings > Connectors > Add custom connector に上記 URL を登録します。

• 認証後の初回実行時に、FormEdge 管理画面の承認ページへの案内が返ります。対象ワークスペースと許可するスコープを選んで承認してください（承認したスコープがそのまま AI が使える操作の範囲。公開には publish 系スコープが必要）
• 承認の一覧・失効は管理画面の「設定 > 外部アプリ接続」からいつでも行えます（失効は即時反映）
• ページは「AI が下書き作成 → プレビューURLで人間が確認 → 公開」の流れを想定しています

全エンドポイントのリクエスト・レスポンス仕様は API リファレンスをご覧ください。