WPForms REST APIおよびAbilities APIリファレンス

更新:
Markdownを表示

WPForms 1.9.9 では、WordPress Abilities API を基盤とした読み取り専用の REST API が導入されました。HTTP クライアント、コマンドライン、独自の PHP コード、または Model Context Protocol (MCP) を話す AI アシスタントから、フォームの一覧表示、フォーム構成の取得、エントリーの取得と検索、フォーム統計情報の取得が可能です。

「WPForms REST API」で検索してここにたどり着いた場合、それがこれです。個別の REST API は存在しません。Abilities API との統合が、WPForms が HTTP 経由でデータを公開する方法です。

Abilities API とは

Abilities API は、WordPress 6.9 で追加された WordPress コア機能です。プラグインは、名前、入力スキーマ、出力スキーマ、および権限コールバックを持つ個別の権限（abilities と呼ばれます）を宣言できます。WordPress は、登録されたすべての能力を REST API で /wp-json/wp-abilities/v1/abilities/<ability>/run で自動的に公開し、公式 MCP アダプタープラグインを通じて MCP 互換の AI クライアントにも公開します。

WPForms は、wpforms/ 名前空間の下に一連の読み取り専用の能力を登録します。各能力は、管理画面で使用されるのと同じ WPForms 権限チェック（wpforms_current_user_can()）を実行するため、REST および MCP のサーフェスは、新しいモデルを導入するのではなく、既存の権限モデルを継承します。

要件:

  • WordPress 6.9 以降
  • WPForms Lite または Pro 1.9.9 以降（一部の能力は Pro のみです。以下の参照表を参照してください）
  • MCP クライアントの場合: wordpress/mcp-adapter プラグイン

能力の呼び出し

各能力は 2 つのトランスポートを通じて呼び出すことができます。結果は同一ですので、呼び出し環境に適した方を選択してください。

REST API

認証済みの GET リクエストを /wp-json/wp-abilities/v1/abilities/<ability>/run に送信します。WPForms のすべての能力は読み取り専用であるため、GET のみが受け入れられ、POST は 405 Method Not Allowed を返します。

注意: パラメータは、input キーの下の角括弧付きクエリ文字列フィールドとして渡します。例: input[limit]=10&input[status]=publish。クライアントが自動的に行わない場合は、角括弧を URL エンコードしてください（[ の場合は %5B、] の場合は %5D）。

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms/run?input%5Blimit%5D=10&input%5Bstatus%5D=publish"

PHP

wp_abilities_api_init アクションが発火した後で実行される任意のプラグイン、テーマ、またはカスタムコードから、wp_get_ability() で能力を取得し、その execute() メソッドを呼び出します。入力は連想配列（各能力のパラメータ表に記載されているのと同じ名前）として渡します。

$ability = wp_get_ability( 'wpforms/list-forms' );

if ( $ability ) {
    $result = $ability->execute(
        [
            'limit'  => 10,
            'status' => 'publish',
        ]
    );

    if ( is_wp_error( $result ) ) {
        // Handle error.
        return;
    }

    // $result['forms']  array of form summaries
    // $result['total']  total count (integer)
}

認証

REST トランスポートは標準の WordPress 認証を使用します。外部クライアントに推奨される方法は、WordPress コアに組み込まれており、追加のプラグインを必要としないアプリケーションパスワードです。

アプリケーションパスワードの生成

  1. 呼び出しを実行する WordPress ユーザーとしてサインインします。
  2. ユーザー » プロフィール に移動し、アプリケーションパスワード セクションまでスクロールします。
  3. 統合の名前を入力し、新しいアプリケーションパスワードを追加をクリックします。
  4. 生成されたパスワードをコピーします。WordPressでは一度しか表示されません。

プログラムでアプリケーションパスワードを管理するためのRESTエンドポイントを含む、より詳細なリファレンスについては、WordPressコアチームのアプリケーションパスワード統合ガイドを参照してください。

認証情報の送信

ユーザー名とアプリケーションパスワードを、すべてのリクエストでHTTP Basic認証として渡します。

curlを使用する場合

このドキュメントの例をそのまま実行できるように、サイトURLを環境変数として設定します。

export WP_SITE="https://your-wordpress-site.com"

次に、すべてのcurlコマンドに-uフラグを追加します。フラグの値は、ユーザー名、コロン、アプリケーションパスワード（スペースなし）です。

Postman、Insomnia、またはその他のクライアントを使用する場合

リクエストの認証タイプをBasic認証に設定し、ユーザー名とアプリケーションパスワードを提供します。クライアントがエンコーディングを処理します。

ヘッダーを手動で設定する

認証情報をbase64エンコードされたAuthorizationヘッダーとして送信します。

ユーザー名とアプリケーションパスワードをコロン（スペースなし）で区切られた単一の文字列に結合し、選択したツール（base64コマンド、オンラインエンコーダー、または言語の標準ライブラリ）を使用して結果をbase64エンコードします。エンコードされた値を、Authorization: Basic <encoded>の形式で、すべてのリクエストのAuthorizationヘッダーとして送信します。

このドキュメントの残りの部分のリクエスト例では、読みやすさのために認証フラグを省略しています。すべての実際のリクエストに-uフラグ（またはAuthorizationヘッダー）を追加してください。そうしないと、APIは401 Unauthorizedを返します。

権限

各機能は、実行前に特定のWPForms権限をチェックします。チェックに失敗すると、HTTPステータス403のWP_Errorが返されます。

機能権限
wpforms/list-formsview_forms
wpforms/get-formview_form_single
wpforms/get-form-stats (Lite)view_form_single
wpforms/get-form-stats (Pro)view_entries_form_single
wpforms/get-entry-summariesview_entries_form_single
wpforms/get-entryview_entry_single
wpforms/search-entries (form_idあり)view_entries_form_single
wpforms/search-entries (form_idなし)エントリーを表示

機能リファレンス

すべての機能は読み取り専用でべき等です。エラーは、code、message、data.statusフィールドを持つJSONにシリアル化されたWP_Errorオブジェクトとして返されます。

注意: 以下のリクエスト例では、表示の簡略化のため認証フラグを省略しています。各呼び出しは認証される必要があります。そうでない場合は401 Unauthorizedが返されます。すべてのcurlコマンドに-uフラグを追加するか（または同等のAuthorization: Basicヘッダーを送信）、認証セクションの詳細を参照してください。

wpforms/list-forms

フォームを要約メタデータとともに一覧表示します。LiteおよびProで利用可能です。

パラメーター

名前タイプ必須デフォルト説明
ステータス文字列いいえ公開フォームのステータス。公開、下書き、ゴミ箱のいずれか。
制限整数いいえ20返されるフォームの最大数。範囲は1から100です。
オフセット整数いいえ0スキップするフォームの数。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms/run?input%5Blimit%5D=10&input%5Bstatus%5D=publish"

レスポンス例

{
  "forms": [
    {
      "id": 123,
      "title": "Contact Form",
      "status": "publish",
      "created": "2026-01-27 10:00:00",
      "modified": "2026-02-15 14:30:00",
      "author": 1
    }
  ],
  "total": 5
}

wpforms/get-form

フォームの設定の厳選されたサブセット、およびオプションでフィールド構成を含む単一のフォームを取得します。LiteおよびProで利用可能です。

パラメーター

名前タイプ必須デフォルト説明
フォームID整数はい—取得するフォームのID。
フィールドを含めるブール値いいえtrueフォームのフィールド構成をレスポンスに含めます。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-form/run?input%5Bform_id%5D=123&input%5Binclude_fields%5D=true"

レスポンス例

{
  "id": 123,
  "title": "Contact Form",
  "status": "publish",
  "created": "2026-01-27 10:00:00",
  "modified": "2026-02-15 14:30:00",
  "author": 1,
  "settings": {
    "form_title": "Contact Form",
    "form_desc": "Get in touch with us",
    "submit_text": "Submit",
    "ajax_submit": true,
    "honeypot": true,
    "antispam": true
  },
  "fields": [
    {
      "id": 1,
      "type": "text",
      "label": "Name",
      "description": "",
      "required": true,
      "size": "medium"
    }
  ]
}

この機能によって返されるsettingsオブジェクトは、厳選された非機密性のサブセット（タイトル、説明、送信テキスト、AJAX送信フラグ、ハニーポット、スパム防止）です。通知、確認、統合の設定は公開されません。

wpforms/get-form-stats

フォームの送信統計を返します。LiteとProではレスポンスの形状が異なります。

パラメーター

名前タイプ必須デフォルト説明
フォームID整数はい—フォームのID。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-form-stats/run?input%5Bform_id%5D=123"

Liteレスポンス

{
  "form_id": 123,
  "entries_available": false,
  "message": "Entry statistics require WPForms Pro. Upgrade to access detailed form submission data."
}

Proレスポンス

{
  "form_id": 123,
  "total_entries": 156,
  "unread_entries": 12,
  "starred_entries": 8,
  "entries_available": true
}

wpforms/get-entry-summaries

単一フォームのエントリ概要のページネーションされたリスト。Proのみ。

パラメーター

名前タイプ必須デフォルト説明
フォームID整数はい—エントリを取得するフォームのID。
ステータス文字列いいえ""partial、abandoned、spam、trashのいずれか。空の場合はすべての完了したエントリを返します。
タイプ文字列いいえ""read、unread、starredのいずれか。
フィールドを含めるブール値いいえfalse各エントリのフィールド値をレスポンスに含めます。
制限整数いいえ20返されるエントリの最大数。範囲は1から100です。
オフセット整数いいえ0スキップするエントリの数。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-entry-summaries/run?input%5Bform_id%5D=123&input%5Btype%5D=unread&input%5Blimit%5D=20"

レスポンス例

{
  "entries": [
    {
      "id": 456,
      "form_id": 123,
      "date": "2026-02-15 14:32:10",
      "status": "",
      "viewed": false,
      "starred": true
    }
  ],
  "total": 15,
  "form_id": 123
}

wpforms/get-entry

IDで単一のエントリを取得します。すべてのフィールド値が含まれます。Proのみ。

パラメーター

名前タイプ必須デフォルト説明
entry_id整数はい—取得するエントリのID。
フィールドを含めるブール値いいえtrueエントリのフィールド値をレスポンスに含めます。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-entry/run?input%5Bentry_id%5D=456"

レスポンス例

{
  "id": 456,
  "form_id": 123,
  "date": "2026-02-15 14:32:10",
  "modified": "2026-02-15 15:00:00",
  "status": "",
  "viewed": true,
  "starred": false,
  "ip_address": "192.168.1.100",
  "fields": [
    {
      "id": 1,
      "name": "Name",
      "value": "John Doe",
      "type": "text"
    }
  ]
}

レスポンスのIPアドレスはマスクできます。サイトのコードに add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) を追加してください。有効にすると、IPv4アドレスの最後の3つのオクテットがアスタリスクに置き換えられます（例： ***.***.***.100）。

wpforms/search-entries

フルテキスト、フィールド固有、ステータス、日付範囲フィルターを使用して、1つまたはすべてのフォームのエントリを検索します。Proのみ。

パラメーター

名前タイプ必須デフォルト説明
フォームID整数いいえ—検索を単一のフォームに制限します。省略すると、すべてのフォームを検索します。
search文字列いいえ""すべてのエントリフィールドに対して一致するフルテキストクエリ。
field_id整数いいえ—検索を特定のフィールドIDに制限します。field_valueと組み合わせて使用します。
field_value文字列いいえ—field_idで指定されたフィールドで一致する正確な値。
date_from文字列いいえ—日付範囲の開始、形式YYYY-MM-DD。
date_to文字列いいえ—日付範囲の終了、形式YYYY-MM-DD。
ステータス文字列いいえ""partial、abandoned、spam、trashのいずれか。
タイプ文字列いいえ""read、unread、starredのいずれか。
フィールドを含めるブール値いいえtrueエントリフィールド値をレスポンスに含めます。
制限整数いいえ201ページあたりの最大エントリ数。範囲は1から100です。
ページ整数いいえ1ページ番号。この機能は、offsetを使用するlist-formsおよびget-entry-summariesとは異なり、ページベースのページネーションを使用することに注意してください。
並べ替え順序文字列いいえ日付entry_id、date、statusのいずれか。
順序文字列いいえ降順ASC、DESCのいずれか。

リクエスト例

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/search-entries/run?input%5Bform_id%5D=5&input%5Bsearch%5D=john%40example.com&input%5Bpage%5D=1&input%5Blimit%5D=20"

レスポンス例

{
  "entries": [
    {
      "id": 142,
      "form_id": 5,
      "date": "2026-02-15 14:32:10",
      "status": "",
      "viewed": false,
      "starred": true,
      "fields": [
        { "id": 1, "name": "Name",  "value": "John Doe",         "type": "text"  },
        { "id": 2, "name": "Email", "value": "[email protected]", "type": "email" }
      ]
    }
  ],
  "total": 47,
  "total_pages": 5,
  "page": 1,
  "limit": 20
}

MCPクライアントでのWPFormsの使用

すべてのWPForms機能はmcp.publicがtrueに設定されて登録されているため、MCP互換のAIクライアント（Claude Desktop、Cursorなど）は、WordPressサイトがwordpress/mcp-adapterプラグインを介して接続されると自動的に検出します。インストール後、WPForms側の追加設定は不要です。機能はクライアントのツールリストのWPFormsカテゴリの下に表示され、REST APIと同じ権限コールバックを尊重します。

機能のプログラムによる検出

IDをハードコーディングする代わりに、サイトで利用可能な機能を列挙するには：

# List all registered abilities on the site
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Fetch the schema for a single ability
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

応答には、各機能のID、ラベル、説明、カテゴリ、および完全な入力および出力スキーマが含まれており、WPForms固有のサーフェスに関する事前知識なしに汎用クライアントを構築するのに十分な情報が含まれています。

まだ解決しませんか？ どうすればお手伝いできますか？
最終更新日: 2026年5月12日