開発者向けドキュメント

• 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 — カスタムドメインの登録・再検証・削除（インフラ設定を変更するため、既定では付与されず発行時の明示選択が必要）
• read:tenant-settings — テナント設定（ブランディング等のワークスペース全体の設定）の参照（既定では付与されず、発行時の明示選択が必要）
• write:tenant-settings — テナント設定の変更（変更が全ページ・全フォームに一括で波及するため、既定では付与されず発行時の明示選択が必要）
• publish:pages — ページの公開・非公開（write:pages とは別の明示選択。下書き作成までを許すキーと公開まで許すキーを分けられます）
• publish:forms — フォームの公開・非公開（publish:pages と同じく発行時の明示選択が必要）
• delete:pages — ページの削除（取り消せないため write:pages とは別の明示選択。削除は公開も同時に止まります）
• delete:forms — フォームの削除（delete:pages と同じく明示選択。投稿データも参照できなくなります）

スコープはキー発行時に必要な範囲だけを選択できます。既定で付くのは read:forms / read:submissions / read:usage / read:attachments / read:pages の 5 つで、それ以外（read:notifications・read:assets・read:custom-domains・read:tenant-settings の各 read 系と、write 系 / publish 系 / delete 系）はすべて発行時の明示選択です。write 系・publish 系は対応する read 系を自動的に含みます（delete 系は応答が 204 で内容を返さないため含みません）。発行後の変更はできないため、変更する場合は失効して再発行してください。

• 一覧系は 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": "This API key does not have the required scope (read:forms). Open \"API keys\" in the FormEdge dashboard and issue a new key with the required scopes.",
  "instance": "/api/ext/v1/forms"
}

detail は英語で返します（AI エージェントがそのまま利用者に提示するため）。プログラムでの判定には status と type を使ってください。

• 401 — APIキーが無効・未指定
• 403 — スコープ不足／プランで API / MCP 連携が利用できない状態（Free へのダウングレード等。アップグレードで既存キーのまま再開できます）／ワークスペースが無効（凍結・解約）／OAuth（MCP）接続が未承認。OAuth 接続の場合はレスポンスの connect_url が復旧先を示します（未承認なら承認ページで接続を承認、スコープ不足なら接続一覧で該当の接続を編集してスコープを追加。編集は接続元アプリの再認証なしで即時反映）。APIキーのスコープ不足は失効して再発行してください
• 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.ai（設定 > コネクタ）と ChatGPT（設定 > アプリ）では、一覧から FormEdge を選んで「接続」するだけで 使えます（公式ディレクトリ掲載済み・URL の入力は不要）。

Claude Code での登録例:

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

その他の MCP クライアント（Cursor 等）は、各クライアントの MCP 設定に上記 URL を登録します。

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

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