API

Magic Form Cloud には、ブラウザから使う公開API（フォーム定義の取得、JSONでの送信、添付ファイルのアップロード）と、APIトークンで使う管理API・デプロイAPIがあります。公開APIはAPIトークン不要で、サイトに登録した接続元から呼び出せます。管理APIはサイトやフォームの作成・更新・公開、受付の取得に、デプロイAPIはツールからのフォームの一括配置に使います。このページでは、各APIのURL、リクエストとレスポンスの形、エラー、制限を説明します。

一覧

公開フォーム定義

GET https://form.magichtml.dev/api/public/v1/sites/SITE_ID/resources/contact

公開中のフォームの定義を返します。サイトのHTMLで入力欄を作ったり、送信前にチェックしたりするのに使えます。

{
  "version": "公開版のID（UUID）",
  "name": "お問い合わせ",
  "kind": "form",
  "fields": [
    { "key": "name", "label": "お名前", "type": "text", "required": true, "public": false },
    { "key": "email", "label": "メールアドレス", "type": "email", "required": true, "public": false },
    { "key": "message", "label": "お問い合わせ内容", "type": "textarea", "required": true, "public": false }
  ],
  "completion": { "redirect": null, "message": null }
}

• 返すのは公開版の内容です。保存しただけの下書きは含みません。
• 通知先などのメール設定と、受付データは含みません。
• フォームが存在しないか公開されていない場合は 404 です。

JSONでの送信

POST https://form.magichtml.dev/api/public/v1/sites/SITE_ID/forms/contact/submissions
Content-Type: application/json
Accept: application/json

{
  "version": "公開版のID",
  "request_id": "6f1c2a4e-8d3b-4c71-9e5a-2b7d0f3a9c18",
  "values": {
    "name": "山田 太郎",
    "email": "taro@example.com",
    "message": "見積もりをお願いします。"
  },
  "_hp": ""
}

values の値は型に合わせます。

レスポンス

入力内容のエラーは、項目ごとのメッセージ（errors）と、コード付きの一覧（violations）で返します。

{
  "message": "入力内容をご確認ください。",
  "errors": {
    "email": ["メールアドレスのメール形式が不正です。"]
  },
  "violations": [
    { "field": "email", "code": "email", "params": {}, "message": "メールアドレスのメール形式が不正です。" }
  ]
}

• violations の各要素は field、code、params（常にオブジェクト）、message を持ちます。コードの一覧は 項目と入力ルール を参照してください。
• version・request_id・values が欠けている、形式が違うといったリクエスト自体の誤りでは、violations のない 422 を返します。

冪等性（同じ送信の再試行）

• 通信が途切れて結果が分からない場合は、同じ request_id と同じ内容で再送してください。すでに受け付けていれば 200 と "duplicate": true が返り、二重に保存されることはありません。
• 同じ request_id で内容を変えると 409（「同じ送信IDで内容を変更することはできません。」）になります。入力を変えたら新しい request_id を使います。
• 新しい送信の version が現在の公開版と違うと 409（「フォームが更新されています。再読み込みしてください。」）になります。定義を取得し直してください。すでに受け付けた送信の再送は、その後に公開版が変わっても重複として成功します。

添付ファイルのアップロード

ファイル項目がある場合、JSON送信の前にファイルを1件ずつアップロードし、受け取ったトークンを送信の値に使います。

POST https://form.magichtml.dev/api/public/v1/sites/SITE_ID/forms/contact/uploads
Content-Type: multipart/form-data
Accept: application/json

成功すると次の形で返ります。新しく保存したときは 201、同じ request_id・項目・内容のファイルをもう一度送ったときは同じトークンを 200 で返します。

{ "token": "トークン（UUID）", "name": "portfolio.pdf", "mime": "application/pdf", "size": 48213 }

• トークンの有効期限は60分です。送信に使われなかったファイルは期限後に削除されます。
• トークンは、アップロード時と同じ request_id・項目・公開版の送信でだけ使え、使えるのは1回の受付だけです。期限切れや無効なトークンでは「（項目名）のファイルの有効期限が切れたか、無効です。ファイルを選び直してください。」（422）になります。
• 形式・サイズ・保存容量の誤りは 422、version が現在の公開版と違うと 409 です。
• 同じ request_id と項目でアップロードできるのは20回までです。超えると 429 になります。

const body = new FormData();
body.append('version', schema.version);
body.append('request_id', requestId);
body.append('field', 'files');
body.append('file', fileInput.files[0]);
const upload = await fetch(`https://form.magichtml.dev/api/public/v1/sites/SITE_ID/forms/contact/uploads`, {
  method: 'POST', body, headers: { Accept: 'application/json' },
}).then(r => r.json());
// 送信時: values.files = [upload.token]

フォームSDKの fetch モードは、このアップロードと送信を自動で行います（フォームSDK）。

リリース固定の公開API

デプロイAPIで作成したリリースには、そのリリースの公開版に固定されたURLがあります。

GET  https://form.magichtml.dev/api/public/v1/sites/SITE_ID/releases/RELEASE_ID/resources/contact
POST https://form.magichtml.dev/api/public/v1/sites/SITE_ID/releases/RELEASE_ID/forms/contact/submissions
POST https://form.magichtml.dev/api/public/v1/sites/SITE_ID/releases/RELEASE_ID/forms/contact/uploads

使い方は通常のURLと同じです。ブラウザからの呼び出しでは、リリース作成時に指定したオリジンだけを受け付けます。

CORS

公開APIは、サイト設定の「許可する接続元」に登録したオリジンからブラウザで呼び出せます。

• 許可したオリジンからのリクエストには Access-Control-Allow-Origin にそのオリジンを返します。
• 使えるメソッドは GET、POST、OPTIONS、リクエストヘッダーは Content-Type と Accept です。プリフライト（OPTIONS）には 204 を返します。
• 登録していないオリジンからのリクエストは 403（「この接続元は許可されていません。」）になります。
• Cookie や認証情報は使いません。fetch では credentials を指定する必要はありません。
• レスポンスには Cache-Control: no-store が付きます。
• 接続元の確認はブラウザが送る Origin ヘッダーに対して行います。

管理API

APIトークン

管理APIとデプロイAPIには、個人用のAPIトークンを使います。

1. 管理画面右上の「アカウント・API」（https://form.magichtml.dev/app/account）を開きます。
2. 「管理APIトークン」に名前を入力し、「トークンを発行」を押します。
3. 表示されたトークンを控えます。トークンはこの画面で一度だけ表示されます。

• 有効期間は発行から90日です。期限が過ぎたトークンは使えなくなるので、新しく発行してください。
• 不要になったトークンは「失効」で無効にできます。
• トークンは自分のサイトすべてを管理できます。公開サイトのHTMLやJavaScriptには絶対に入れないでください。

リクエストには Authorization ヘッダーで付けます。

curl -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" \
  https://form.magichtml.dev/api/v1/sites

トークンがない・誤っている・期限切れの場合は 401 です。他のアカウントのサイトやフォームを指定すると 404 になります。

ルート一覧

{site}・{resource}・{submission}・{file} はそれぞれのID（UUID）です。レスポンスは、多くの場合 data の中に対象のデータを入れて返します。

リクエストの注意

• サイトの更新: name（100文字まで）、retention_days（1〜3650）が必須です。origins はオリジンの配列（最大20件、https://example.com の形式でパスを含めない）です。
• フォームの作成: key は英小文字で始まり、英小文字・数字・_・- で80文字まで、サイト内で重複できません。作成直後の項目は お名前・メールアドレス・お問い合わせ内容 の3つです。
• フォームの更新: version には、取得したフォームの version（下書きの更新番号。公開版のIDとは別です）を送ります。その間に別の操作で更新されていると 409（「別の操作で更新されています。再読み込みしてください。」）になるので、取得し直してから更新します。fields の形式は 項目と入力ルール、settings のキーは次の表のとおりです。既存の項目（同じキーで同じ型）で省略したプロパティは、以前の値が保持されます。
• 更新は下書きへの保存です。反映するには publish を呼びます。

管理APIは、ユーザーごとに1分あたり120リクエストまでです。

デプロイAPI

PUT https://form.magichtml.dev/api/v1/form-deployments/{deployment}/releases/{release}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

サイト制作ツールなどが、フォーム一式をまとめて作成・更新・公開するためのAPIです。{deployment}（配置先ごと）と {release}（配置操作ごと）は、呼び出す側が生成するUUIDです。

{
  "name": "サイト名",
  "origin": "https://example.com",
  "forms": [
    {
      "key": "contact",
      "name": "お問い合わせ",
      "fields": [
        { "key": "email", "label": "メールアドレス", "type": "email", "required": true, "public": false }
      ],
      "settings": {
        "notify_enabled": false,
        "reply_enabled": false,
        "notify_subject": "{{form_name}}へのお問い合わせ",
        "notify_body": "{{all_fields}}",
        "reply_subject": "お問い合わせを受け付けました",
        "reply_body": "{{all_fields}}"
      }
    }
  ]
}

• origin はフォームを置くサイトのHTTPSのオリジンです（パスなし）。forms は1〜100件で、各 settings には notify_enabled と reply_enabled が必須です。
• 初めての {deployment} では、サイトを作成して origin を接続元に登録します。以降は同じサイトを更新します。
• 呼び出しごとに、各フォームを作成または更新して公開し、その公開版を {release} に記録します。

{
  "site_id": "サイトID",
  "release_id": "リリースID",
  "endpoint": "https://form.magichtml.dev/api/public/v1/sites/SITE_ID/releases/RELEASE_ID",
  "versions": { "contact": "公開版のID" }
}

• endpoint はリリース固定の公開APIのベースURLです。HTMLフォームでは https://form.magichtml.dev/f/SITE_ID/releases/RELEASE_ID/contact に送信できます。古いリリースのURLは、その後に新しいリリースを作っても、それぞれ記録された公開版で受け付けます（フォームが公開停止された場合を除く）。
• 冪等性: 同じ {release} に同じ内容を送ると、同じ結果を返します。内容が違うと 409 です。
• 手動の変更を上書きしない: このAPIで作ったフォームが前回の呼び出しの後に管理画面などで変更されていた場合（下書きの保存、公開、公開停止、版の切り替えを含む）、またはこのAPIで作っていない同じ識別キーのフォームがある場合は 409 で止まり、何も上書きしません。origin がサイトの接続元に含まれていない場合も 409 です。
• 検証: notify_enabled が true なのに notify_to が空、reply_enabled が true なのに reply_field が空の場合は 422 です。メールを有効にしたのにサービス側のメール配信が設定されていない場合も 422 になります。

バックアップ（書き出し）

サイトのフォームを、バックアップ用のZIP（MagicHTML形式、site.magichtml.zip）として書き出せます。

• 管理画面: サイト画面の「書き出し」から「管理用ZIPをダウンロード」
• API: GET https://form.magichtml.dev/api/v1/sites/SITE_ID/interchange/export

• ZIPには通知先などのメールアドレスが含まれます。公開サイトのフォルダには置かないでください。
• ZIPの取り込み（インポート）には対応していません。

制限のまとめ

制限を超えると 429（大きさの場合は 413）が返ります。