Référence de l'API REST et de l'API Abilities de WPForms

WPForms 1.9.9 a introduit une API REST en lecture seule basée sur l'API Abilities de WordPress. Vous pouvez lister les formulaires, récupérer la configuration des formulaires, récupérer et rechercher des entrées, et extraire des statistiques de formulaires à partir de n'importe quel client HTTP, de la ligne de commande, de votre propre code PHP ou d'assistants IA qui parlent le Model Context Protocol (MCP).

Si vous avez recherché « WPForms REST API » et que vous êtes arrivé ici, c'est bien cela. Il n'y a pas d'API REST distincte ; l'intégration de l'API Abilities est la manière dont WPForms expose ses données sur HTTP.

Qu'est-ce que l'API Abilities

L'API Abilities est une fonctionnalité du cœur de WordPress ajoutée dans WordPress 6.9. Elle permet aux plugins de déclarer des capacités individuelles (appelées abilities) avec un nom, un schéma d'entrée, un schéma de sortie et une fonction de rappel de permission. WordPress expose ensuite automatiquement chaque capacité enregistrée via l'API REST à l'adresse /wp-json/wp-abilities/v1/abilities/<ability>/run et aux clients IA compatibles MCP via le plugin officiel de l'adaptateur MCP.

WPForms enregistre un ensemble de capacités en lecture seule sous l'espace de noms wpforms/. Chaque capacité exécute les mêmes vérifications de capacités de WPForms utilisées dans l'administration (wpforms_current_user_can()), de sorte que les surfaces REST et MCP héritent du modèle de permission existant plutôt que d'en introduire un nouveau.

Appeler une capacité

Chaque capacité peut être invoquée via deux transports. Le résultat est identique ; choisissez celui qui convient à l'environnement d'appel.

API REST

Envoyez une requête GET authentifiée à /wp-json/wp-abilities/v1/abilities/<ability>/run. Étant donné que chaque capacité WPForms est en lecture seule, seul GET est accepté ; POST renvoie 405 Method Not Allowed.

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

PHP

Depuis n'importe quel plugin, thème ou code personnalisé qui s'exécute après le déclenchement de l'action wp_abilities_api_init, récupérez la capacité avec wp_get_ability() et appelez sa méthode execute(). Transmettez l'entrée sous forme de tableau associatif de paramètres (les mêmes noms que ceux listés dans le tableau des paramètres de chaque capacité).

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

Authentification

Le transport REST utilise l'authentification standard de WordPress. La méthode recommandée pour les clients externes est Mots de passe d'application, qui sont intégrés au cœur de WordPress et ne nécessitent aucun plugin supplémentaire.

Générer un mot de passe d'application

1. Connectez-vous en tant qu'utilisateur WordPress sous lequel les appels doivent s'exécuter.
2. Accédez à Utilisateurs » Profil et faites défiler jusqu'à la section Mots de passe d'application.
3. Entrez un nom pour l'intégration et cliquez sur Ajouter un nouveau mot de passe d'application.
4. Copiez le mot de passe généré. WordPress ne l'affiche qu'une seule fois.

Pour une référence plus approfondie, y compris les points d'accès REST pour gérer les mots de passe d'application par programme, consultez le Guide d'intégration des mots de passe d'application de l'équipe principale de WordPress.

Envoi des identifiants

Transmettez le nom d'utilisateur et le mot de passe de l'application en authentification HTTP Basic à chaque requête.

Avec curl

Définissez l'URL de votre site comme variable d'environnement afin que les exemples de cette documentation soient exécutables tels quels :

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

Ajoutez ensuite le drapeau -u à chaque commande curl. La valeur du drapeau est votre nom d'utilisateur, suivi d'un deux-points, suivi de votre mot de passe d'application (sans espaces).

Avec Postman, Insomnia ou d'autres clients

Définissez le type d'Authentification de la requête sur Authentification de base et fournissez votre nom d'utilisateur et votre mot de passe d'application. Le client gère l'encodage pour vous.

Définition manuelle de l'en-tête

Envoyez vos identifiants dans un en-tête Authorization encodé en base64 :

Combinez votre nom d'utilisateur et votre mot de passe d'application en une seule chaîne, séparés par un deux-points (sans espaces), et encodez le résultat en base64 à l'aide d'un outil de votre choix (commande base64, encodeur en ligne ou bibliothèque standard de votre langage). Envoyez la valeur encodée à chaque requête sous la forme Authorization: Basic <encoded>.

Les exemples de requêtes dans le reste de cette documentation omettent le drapeau d'authentification pour plus de lisibilité. Ajoutez le drapeau -u (ou l'en-tête Authorization) à chaque requête réelle, sinon l'API renverra 401 Unauthorized.

Permissions

Chaque capacité vérifie une capacité spécifique de WPForms avant l'exécution. Les vérifications échouées renvoient une WP_Error avec le statut HTTP 403.

Référence de capacité

Toutes les capacités sont en lecture seule et idempotentes. Les erreurs sont renvoyées sous forme d'objets WP_Error sérialisés en JSON avec les champs code, message et data.status.

wpforms/list-forms

Lister les formulaires avec des métadonnées récapitulatives. Disponible en Lite et Pro.

Paramètres

Exemple de requête

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

Exemple de réponse

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

Récupérer un seul formulaire, y compris un sous-ensemble organisé de ses paramètres et, éventuellement, sa configuration de champ. Disponible en Lite et Pro.

Paramètres

Exemple de requête

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

Exemple de réponse

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

L'objet settings renvoyé par cette capacité est un sous-ensemble organisé et non sensible (titre, description, texte de soumission, indicateur de soumission AJAX, honeypot, anti-spam). Les paramètres de notification, de confirmation et d'intégration ne sont pas exposés.

wpforms/get-form-stats

Renvoyer les statistiques de soumission pour un formulaire. La forme de la réponse diffère entre Lite et Pro.

Paramètres

Exemple de requête

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

Réponse Lite

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

Réponse Pro

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

wpforms/get-entry-summaries

Liste paginée des résumés d'entrées pour un seul formulaire. Pro uniquement.

Paramètres

Exemple de requête

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"

Exemple de réponse

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

Récupérer une seule entrée par ID, y compris toutes les valeurs de champ. Pro uniquement.

Paramètres

Exemple de requête

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

Exemple de réponse

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

L'adresse IP dans la réponse peut être masquée. Ajoutez add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) au code de votre site ; lorsqu'il est activé, les adresses IPv4 apparaissent avec leurs trois derniers octets remplacés par des astérisques (par exemple, ***.***.***.100).

wpforms/search-entries

Recherchez des entrées dans un ou tous les formulaires avec des filtres de texte intégral, spécifiques aux champs, de statut et de plage de dates. Pro uniquement.

Paramètres

Exemple de requête

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"

Exemple de réponse

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

Utilisation de WPForms avec les clients MCP

Chaque capacité WPForms est enregistrée avec mcp.public défini sur true, ce qui signifie que les clients IA compatibles MCP (Claude Desktop, Cursor, et autres) les découvrent automatiquement une fois le site WordPress connecté via le plugin wordpress/mcp-adapter. Après l'installation, aucune configuration supplémentaire côté WPForms n'est requise ; les capacités apparaissent dans la liste des outils du client sous la catégorie WPForms et respectent les mêmes rappels de permission que ceux utilisés par l'API REST.

Découverte programmatique des capacités

Pour énumérer les capacités disponibles sur un site au lieu de coder en dur leurs identifiants :

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

La réponse inclut l'ID, le libellé, la description, la catégorie et les schémas d'entrée et de sortie complets de chaque capacité, ce qui est suffisant pour construire un client générique sans connaissance préalable de la surface spécifique à WPForms.

Liens connexes

• Introduction à l'API des capacités WordPress (developer.wordpress.org)
• wordpress/mcp-adapter sur GitHub
• Protocole de contexte de modèle