WPForms REST API und Abilities API Referenz

WPForms 1.9.9 führte eine schreibgeschützte REST-API ein, die auf der WordPress Abilities API aufbaut. Sie können Formulare auflisten, die Formular-Konfiguration abrufen, Einträge abrufen und durchsuchen sowie Formularstatistiken von jedem HTTP-Client, der Befehlszeile, Ihrem eigenen PHP-Code oder KI-Assistenten, die das Model Context Protocol (MCP) sprechen, abrufen.

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 schreibgeschützten Abilities unter dem Namespace wpforms/. Jede Ability führt dieselben WPForms-Berechtigungsprüfungen durch wie im Admin-Bereich (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 GET-Anfrage an /wp-json/wp-abilities/v1/abilities/<ability>/run. Da jede WPForms-Ability schreibgeschützt ist, wird nur GET akzeptiert; POST 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.

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.

Fähigkeitsreferenz

Alle Fähigkeiten sind schreibgeschützt und idempotent. Fehler werden als WP_Error-Objekte zurückgegeben, die als JSON mit den Feldern code, message und data.status 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
}

WPForms mit MCP-Clients verwenden

Jede WPForms-Funktion wird mit mcp.public auf true registriert, was bedeutet, dass MCP-kompatible KI-Clients (Claude Desktop, Cursor und andere) sie automatisch erkennen, sobald die WordPress-Site über das Plugin wordpress/mcp-adapter verbunden ist. Nach der Installation ist keine weitere Konfiguration auf der WPForms-Seite erforderlich; die Funktionen erscheinen 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.

Verwandte Links

• Einführung in die WordPress Abilities API (developer.wordpress.org)
• wordpress/mcp-adapter auf GitHub
• Model Context Protocol