WPForms REST API und Abilities API Referenz

WPForms 1.9.9 führte eine REST-API ein, die auf der WordPress Abilities API aufbaut, und WPForms 1.10.2 erweiterte sie um eine Opt-in-Schreibunterstützung. Sie können Formulare auflisten, die Formular-Konfiguration abrufen, Einträge abrufen und durchsuchen sowie Formularstatistiken abrufen und, sobald der Schreibzugriff aktiviert ist, Formulare erstellen, Felder hinzufügen und aktualisieren und sichere Formulareinstellungen aktualisieren. Jede Fähigkeit funktioniert von jedem HTTP-Client, der Befehlszeile, Ihrem eigenen PHP-Code oder KI-Assistenten, die das Model Context Protocol (MCP) sprechen.

Wenn Sie nach „WPForms REST API“ gesucht und hier gelandet sind, dann ist es das. Es gibt keine separate REST-API; die Abilities API-Integration ist, wie WPForms seine Daten über HTTP bereitstellt.

Was ist die Abilities API

Die Abilities API ist eine Kernfunktion von WordPress, die in WordPress 6.9 hinzugefügt wurde. Sie ermöglicht es Plugins, einzelne Berechtigungen (sogenannte Abilities) mit einem Namen, einem Eingabeschema, einem Ausgabeschema und einer Berechtigungs-Callback-Funktion zu deklarieren. WordPress stellt dann jede registrierte Ability automatisch über die REST-API unter /wp-json/wp-abilities/v1/abilities/<ability>/run und für MCP-kompatible KI-Clients über das offizielle MCP-Adapter-Plugin bereit.

WPForms registriert eine Reihe von Fähigkeiten unter dem Namespace wpforms/. Die Lesefähigkeiten sind seit WPForms 1.9.9 verfügbar. WPForms 1.10.2 fügte eine Reihe von Schreibfähigkeiten hinzu, die standardmäßig deaktiviert sind (siehe Schreibzugriff aktivieren unten). Jede Fähigkeit führt die gleichen WPForms-Berechtigungsprüfungen durch, die auch im Admin-Bereich verwendet werden (wpforms_current_user_can()), sodass die REST- und MCP-Oberflächen das bestehende Berechtigungsmodell erben, anstatt ein neues einzuführen.

Aufrufen einer Ability

Jede Ability kann über zwei Transports aufgerufen werden. Das Ergebnis ist identisch; wählen Sie, was immer zur aufrufenden Umgebung passt.

REST API

Senden Sie eine authentifizierte Anfrage an /wp-json/wp-abilities/v1/abilities/<ability>/run. Die HTTP-Methode hängt von der Fähigkeit ab: Lesefähigkeiten verwenden GET und Schreibfähigkeiten verwenden POST. Das Aufrufen einer Fähigkeit mit der falschen Methode gibt 405 Method Not Allowed zurück.

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

PHP

Rufen Sie von jedem Plugin, Theme oder benutzerdefinierten Code, der nach dem Auslösen der Aktion wp_abilities_api_init ausgeführt wird, die Ability mit wp_get_ability() ab und rufen Sie deren execute()-Methode auf. Übergeben Sie die Eingabe als assoziatives Array von Parametern (denselben Namen, die in der Parametertabelle jeder Ability aufgeführt sind).

$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)
}

Authentifizierung

Der REST-Transport verwendet die Standard-WordPress-Authentifizierung. Die empfohlene Methode für externe Clients sind Anwendungspasswörter, die in den WordPress-Kern integriert sind und kein zusätzliches Plugin erfordern.

Generieren eines Anwendungspassworts

1. Melden Sie sich als der WordPress-Benutzer an, unter dessen Berechtigungen die Aufrufe ausgeführt werden sollen.
2. Gehen Sie zu Benutzer » Profil und scrollen Sie zum Abschnitt Anwendungspasswörter.
3. Geben Sie einen Namen für die Integration ein und klicken Sie auf Neues Anwendungspasswort hinzufügen.
4. Kopieren Sie das generierte Passwort. WordPress zeigt es nur einmal an.

Für eine detailliertere Referenz, einschließlich REST-Endpunkten zur programmatischen Verwaltung von Anwendungspasswörtern, lesen Sie die Anleitung zur Integration von Anwendungspasswörtern des WordPress-Kernteams.

Übermittlung der Anmeldedaten

Übergeben Sie den Benutzernamen und das Anwendungspasswort als HTTP Basic Authentication bei jeder Anfrage.

Mit curl

Legen Sie Ihre Website-URL als Umgebungsvariable fest, damit die Beispiele in dieser Dokumentation direkt ausführbar sind:

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

Fügen Sie dann das Flag -u zu jedem curl-Befehl hinzu. Der Wert des Flags ist Ihr Benutzername, gefolgt von einem Doppelpunkt, gefolgt von Ihrem Anwendungspasswort (keine Leerzeichen).

Mit Postman, Insomnia oder anderen Clients

Stellen Sie den Auth-Typ der Anfrage auf Basic Auth ein und geben Sie Ihren Benutzernamen und Ihr Anwendungspasswort an. Der Client kümmert sich um die Kodierung für Sie.

Manuelles Festlegen des Headers

Senden Sie Ihre Anmeldedaten als base64-kodierten Authorization-Header:

Kombinieren Sie Ihren Benutzernamen und Ihr Anwendungspasswort zu einer einzigen Zeichenkette, getrennt durch einen Doppelpunkt (keine Leerzeichen), und kodieren Sie das Ergebnis mit base64 unter Verwendung eines Tools Ihrer Wahl (base64-Befehl, ein Online-Encoder oder die Standardbibliothek Ihrer Sprache). Senden Sie den kodierten Wert bei jeder Anfrage als Authorization-Header im Format Authorization: Basic <encoded>.

Die Anfragebeispiele im Rest dieser Dokumentation lassen das Authentifizierungsflag zur besseren Lesbarkeit weg. Fügen Sie das -u-Flag (oder den Authorization-Header) zu jeder echten Anfrage hinzu, andernfalls gibt die API 401 Unauthorized zurück.

Schreibzugriff aktivieren

Die Lesefähigkeiten sind immer verfügbar. Die Schreibfähigkeiten (wpforms/create-form, wpforms/add-field, wpforms/update-field und wpforms/update-form-settings) sind standardmäßig deaktiviert und müssen aktiviert werden, bevor sie ausgeführt werden. Es gibt zwei Möglichkeiten, sie zu aktivieren, und der Filter hat immer das letzte Wort.

Schreibvorgänge im Code aktivieren

Schreibvorgänge programmatisch mit dem Filter wpforms_integrations_abilities_allow_write aktivieren:

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

Der Filter überschreibt den No-Code-Schalter in beide Richtungen. Wenn true zurückgegeben wird, werden Schreibvorgänge aktiviert, auch wenn der Schalter ausgeschaltet ist, und wenn false zurückgegeben wird, werden sie deaktiviert, auch wenn der Schalter eingeschaltet ist. Dies stellt sicher, dass bestehende Entwickler-Setups unverändert funktionieren.

Schreibvorgänge ohne Code aktivieren

Websitebesitzer können Schreibvorgänge von WPForms » Tools » AI MCP mit dem Schalter MCP-Schreibzugriff aktivieren aktivieren, der im Schlüssel ai-mcp-write-enabled der Option wpforms_settings gespeichert wird. Der obige Filter hat Vorrang vor diesem Schalter. Die vollständige Anleitung finden Sie unter WPForms mit KI-Assistenten verwenden.

Berechtigungen

Jede Fähigkeit prüft eine bestimmte WPForms-Berechtigung, bevor sie ausgeführt wird. Fehlgeschlagene Prüfungen geben einen WP_Error mit dem HTTP-Status 403 zurück.

Die in WPForms 1.10.2 eingeführten Schreibfähigkeiten erzwingen dasselbe Berechtigungsmodell. wpforms/create-form erfordert die Berechtigung zum Erstellen von Formularen, und wpforms/add-field, wpforms/update-field und wpforms/update-form-settings erfordern die Berechtigung zum Bearbeiten des Zielformulars. Eine fehlgeschlagene Prüfung gibt einen WP_Error mit dem HTTP-Status 403 zurück. Schreibfähigkeiten erfordern außerdem, dass der Schreibzugriff aktiviert ist, wie oben beschrieben.

Fähigkeitsreferenz

Die Lese-Fähigkeiten sind idempotent und können sicher wiederholt aufgerufen werden. Die Schreib-Fähigkeiten, die in WPForms 1.10.2 eingeführt wurden, erstellen oder ändern Formulardaten und erfordern, dass der Schreibzugriff zuerst aktiviert wird. Fehler werden als WP_Error-Objekte zurückgegeben, die mit den Feldern code, message und data.status in JSON serialisiert sind.

wpforms/list-forms

Formulare mit zusammenfassenden Metadaten auflisten. Verfügbar in Lite und Pro.

Parameter

Beispielanfrage

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

Beispielantwort

{
  "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

Ein einzelnes Formular abrufen, einschließlich einer kuratierten Teilmenge seiner Einstellungen und optional seiner Feldkonfiguration. Verfügbar in Lite und Pro.

Parameter

Beispielanfrage

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

Beispielantwort

{
  "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"
    }
  ]
}

Das von dieser Fähigkeit zurückgegebene settings-Objekt ist eine kuratierte, nicht sensible Teilmenge (Titel, Beschreibung, Absendetext, AJAX-Absende-Flag, Honeypot, Anti-Spam). Benachrichtigungs-, Bestätigungs- und Integrationseinstellungen werden nicht angezeigt.

wpforms/get-form-stats

Einreichungsstatistiken für ein Formular zurückgeben. Die Antwortstruktur unterscheidet sich zwischen Lite und Pro.

Parameter

Beispielanfrage

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

Lite-Antwort

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

Pro-Antwort

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

wpforms/get-entry-summaries

Paginierte Liste von Eintragszusammenfassungen für ein einzelnes Formular. Nur Pro.

Parameter

Beispielanfrage

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"

Beispielantwort

{
  "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

Ruft einen einzelnen Eintrag anhand der ID ab, einschließlich aller Feldwerte. Nur Pro.

Parameter

Beispielanfrage

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

Beispielantwort

{
  "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"
    }
  ]
}

Die IP-Adresse in der Antwort kann maskiert werden. Fügen Sie add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) zum Code Ihrer Website hinzu; wenn aktiviert, erscheinen IPv4-Adressen mit ihren letzten drei Oktetten, die durch Sternchen ersetzt sind (z. B. ***.***.***.100).

wpforms/search-entries

Durchsucht Einträge eines einzelnen Formulars oder aller Formulare mit Volltext-, feldspezifischen-, Status- und Datumsbereichsfiltern. Nur Pro.

Parameter

Beispielanfrage

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"

Beispielantwort

{
  "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
}

Die unten aufgeführten Fähigkeiten wurden in WPForms 1.10.2 hinzugefügt. Alle erfordern, dass der Schreibzugriff aktiviert ist (siehe Schreibzugriff aktivieren), mit Ausnahme von wpforms/describe-editing-schema, das eine Lese-Fähigkeit ist, die verwendet wird, um zu ermitteln, was die Schreib-Fähigkeiten akzeptieren. Die Schreib-Fähigkeiten laufen als POST-Anfragen über REST oder über execute() in PHP.

wpforms/describe-editing-schema

Gibt die Feldtypen und Formulareinstellungen zurück, die die Schreibfähigkeiten auf dieser Website akzeptieren. Rufen Sie dies zuerst auf, da die verfügbaren Feldtypen vom Lizenzlevel abhängen. Verfügbar in Lite und Pro.

Beispielanfrage

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/describe-editing-schema/run?input%5B%5D="

Beispielantwort (gekürzt)

{
  "field_types": [
    {
      "type": "text",
      "label": "Single Line Text",
      "properties": [
        { "key": "label",         "schema": { "type": "string" } },
        { "key": "required",      "schema": { "type": "boolean" } },
        { "key": "size",          "schema": { "type": "string", "enum": ["small", "medium", "large"] } },
        { "key": "placeholder",   "schema": { "type": "string" } },
        { "key": "default_value", "schema": { "type": "string" } }
      ],
      "required_props": []
    },
    {
      "type": "select",
      "label": "Dropdown",
      "properties": [
        { "key": "choices", "schema": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label"] } } },
        { "key": "style",   "schema": { "type": "string", "enum": ["classic", "modern"] } }
      ],
      "required_props": []
    }
  ],
  "form_settings": [
    { "key": "form_title",  "schema": { "type": "string" }, "description": "The form title." },
    { "key": "form_desc",   "schema": { "type": "string" }, "description": "The form description." },
    { "key": "submit_text", "schema": { "type": "string" }, "description": "The submit button label." }
  ]
}

Auf Pro listet field_types text, textarea, email, number, select, radio, checkbox, name, phone, date-time und file-upload auf. Auf Lite ist die Menge die Basis acht: text, textarea, email, number, select, radio, checkbox und name. Die Slugs entsprechen dem Builder, sodass das Feld Dropdown select und das Feld Date / Time date-time ist.

Feldeigenschaften

Die Fähigkeiten create-form, add-field und update-field akzeptieren diese Feldeigenschaften. Jede Eigenschaft gilt nur für die Feldtypen, die sie deklarieren, wie von describe-editing-schema berichtet.

wpforms/create-form

Erstellen Sie ein neues Formular mit einer optionalen Reihe von Feldern und Einstellungen in einem einzigen Aufruf. Verfügbar in Lite und Pro.

Parameter

Beispielanfrage

$ability = wp_get_ability( 'wpforms/create-form' );

$result = $ability->execute(
    [
        'title'  => 'Job Application',
        'fields' => [
            [ 'type' => 'name',   'label' => 'Your Name', 'required' => true ],
            [ 'type' => 'email',  'label' => 'Email',      'required' => true ],
            [ 'type' => 'select', 'label' => 'Position',   'choices' => [ [ 'label' => 'Baker' ], [ 'label' => 'Cashier' ] ] ],
        ],
        'settings' => [
            'form_title'  => 'Job Application',
            'form_desc'   => 'Apply to join our team.',
            'submit_text' => 'Apply Now',
        ],
    ]
);

Beispielantwort

{
  "form_id": 1102,
  "fields": [
    { "id": 0, "type": "name" },
    { "id": 1, "type": "email" },
    { "id": 2, "type": "select" }
  ]
}

wpforms/add-field

Fügen Sie ein neues Feld zu einem vorhandenen Formular hinzu. Verfügbar in Lite und Pro.

Parameter

Übergeben Sie alle Feldeigenschaften für den gewählten Typ zusammen mit form_id und type (siehe die Tabelle der Feldeigenschaften oben). Feldeigenschaften, die Sie weglassen, bleiben unverändert.

Beispielanfrage

$ability = wp_get_ability( 'wpforms/add-field' );

$result = $ability->execute(
    [
        'form_id'  => 1102,
        'type'     => 'phone',
        'label'    => 'Phone',
        'required' => true,
    ]
);

Beispielantwort

{
  "form_id": 1102,
  "field_id": 6,
  "type": "phone"
}

wpforms/update-field

Aktualisieren Sie die Eigenschaften eines vorhandenen Feldes. Verfügbar in Lite und Pro.

Parameter

Übergeben Sie die Feldeigenschaften, die Sie ändern möchten, zusammen mit form_id und field_id (siehe die Tabelle der Feldeigenschaften oben). Eigenschaften, die Sie weglassen, bleiben unverändert. Wenn Sie choices senden, wird die neue Liste nach Index mit den vorhandenen Auswahlmöglichkeiten zusammengeführt.

Beispielanfrage

$ability = wp_get_ability( 'wpforms/update-field' );

$result = $ability->execute(
    [
        'form_id'     => 1102,
        'field_id'    => 6,
        'required'    => true,
        'placeholder' => 'e.g. 555-123-4567',
    ]
);

Beispielantwort

{
  "form_id": 1102,
  "field_id": 6,
  "updated": ["required", "placeholder"],
  "ignored": []
}

wpforms/update-form-settings

Aktualisieren Sie die sicheren Einstellungen eines Formulars. Die Whitelist der Version 1 umfasst form_title, form_desc und submit_text. Verfügbar in Lite und Pro.

Parameter

Beispielanfrage

$ability = wp_get_ability( 'wpforms/update-form-settings' );

$result = $ability->execute(
    [
        'form_id'  => 1102,
        'settings' => [
            'submit_text' => 'Send Application',
        ],
    ]
);

Beispielantwort

{
  "form_id": 1102,
  "updated": ["submit_text"],
  "ignored": []
}

Schlüssel, die nicht auf der Whitelist stehen, werden im ignored-Array zurückgegeben, anstatt einen Fehler zu verursachen. Zum Beispiel wird ajax_submit unverändert zurückgegeben und unter ignored aufgeführt.

WPForms mit MCP-Clients verwenden

Die Lese-Fähigkeiten werden mit mcp.public auf true registriert, sodass MCP-kompatible KI-Clients (Claude Desktop, Cursor und andere) sie automatisch erkennen, sobald die WordPress-Site über das Plugin wordpress/mcp-adapter verbunden ist. Die Schreib-Fähigkeiten und wpforms/describe-editing-schema werden MCP nur dann zur Verfügung gestellt, wenn der Schreibzugriff aktiviert ist. Solange Schreibvorgänge deaktiviert sind, ist ihr mcp.public-Flag auf false gesetzt und sie sind für die MCP-Erkennung verborgen. Daher kann ein Assistent melden, dass er die WPForms-Schreibwerkzeuge nicht finden kann. Sobald eine Website verbunden ist und der Schreibzugriff aktiviert ist, erscheinen die Fähigkeiten in der Tool-Liste des Clients unter der Kategorie WPForms und respektieren dieselben Berechtigungs-Callbacks, die von der REST-API verwendet werden.

Funktionen programmatisch entdecken

Um die auf einer Website verfügbaren Funktionen aufzulisten, anstatt ihre IDs fest zu codieren:

# 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"

Die Antwort enthält die ID, die Bezeichnung, die Beschreibung, die Kategorie sowie die vollständigen Eingabe- und Ausgabeschemata jeder Funktion, was ausreicht, um einen generischen Client zu erstellen, ohne vorherige Kenntnisse der WPForms-spezifischen Oberfläche zu haben.

Die Schreib-Fähigkeiten erscheinen in diesem Index auf jeder Website, auf der WPForms 1.10.2 oder neuer ausgeführt wird, unabhängig davon, ob der Schreibzugriff aktiviert ist oder nicht. Ihr mcp.public-Flag spiegelt jedoch den Schreibzugriffsstatus wider: Es ist nur dann true, wenn Schreibvorgänge aktiviert sind. Deshalb sehen MCP-Clients die Schreibwerkzeuge erst, nachdem der Schreibzugriff aktiviert wurde.

Erweiterung der Feld-Registry

Die Feldtypen und Eigenschaften, die die Schreib-Fähigkeiten akzeptieren, sind in einer erweiterbaren Registry definiert. Add-ons können ihre eigenen Feldtypen und Eigenschaften über zwei Filter registrieren, sodass ein benutzerdefinierter Feldtyp oder ein Add-on-Feldtyp für create-form, add-field und update-field verfügbar wird.

• wpforms_integrations_abilities_field_registry_types registriert neue Feldtypen. Jeder Typ deklariert seine Verfügbarkeit durch einen requires-Wert, der entweder der String pro, eine Add-on-Slug oder ein Callable ist, und kann seine erforderlichen Eigenschaften angeben.
• wpforms_integrations_abilities_field_registry_properties trägt neue Eigenschaftsdefinitionen bei, auf die Feldtypen verweisen können.

add_filter(
    'wpforms_integrations_abilities_field_registry_types',
    function ( $types ) {
        // Register one or more field types here, then return the list.
        return $types;
    }
);

Verwandte Links

• Verwendung von WPForms mit KI-Assistenten, der No-Code-Leitfaden zum Verbinden eines KI-Assistenten
• Einführung in die WordPress Abilities API (developer.wordpress.org)
• wordpress/mcp-adapter auf GitHub
• Model Context Protocol