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

WPForms 1.9.9 a introduit une API REST basée sur l'API Abilities de WordPress, et WPForms 1.10.2 l'a étendue avec une prise en charge d'écriture facultative. 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, et, une fois l'accès en écriture activé, créer des formulaires, ajouter et mettre à jour des champs, et mettre à jour des paramètres de formulaire sécurisés. Chaque capacité fonctionne depuis n'importe quel client HTTP, la ligne de commande, votre propre code PHP, ou des assistants IA qui parlent le protocole 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 sous l'espace de noms wpforms/. Les capacités de lecture sont disponibles depuis WPForms 1.9.9. WPForms 1.10.2 a ajouté un ensemble de capacités d'écriture qui sont désactivées par défaut (voir Activation de l'accès en écriture ci-dessous). Chaque capacité exécute les mêmes vérifications de capacités 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 authentifiée à /wp-json/wp-abilities/v1/abilities/<ability>/run. La méthode HTTP dépend de la capacité : les capacités de lecture utilisent GET, et les capacités d'écriture utilisent POST. Appeler une capacité avec la mauvaise méthode 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.

Activation de l'accès en écriture

Les capacités de lecture sont toujours disponibles. Les capacités d'écriture (wpforms/create-form, wpforms/add-field, wpforms/update-field et wpforms/update-form-settings) sont désactivées par défaut et doivent être activées avant de pouvoir être exécutées. Il existe deux façons de les activer, et le filtre a toujours le dernier mot.

Activation des écritures dans le code

Activez les écritures par programmation avec le filtre wpforms_integrations_abilities_allow_write :

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

Le filtre remplace le commutateur sans code dans les deux sens. Retourner true active les écritures même lorsque le commutateur est désactivé, et retourner false les désactive même lorsque le commutateur est activé. Cela permet aux configurations existantes des développeurs de continuer à fonctionner sans modification.

Activation des écritures sans code

Les propriétaires de sites peuvent activer les écritures depuis WPForms » Outils » AI MCP avec le bouton Activer l'accès en écriture MCP, qui est conservé dans la clé ai-mcp-write-enabled de l'option wpforms_settings. Le filtre ci-dessus a priorité sur ce bouton. Pour le guide complet, consultez Utiliser WPForms avec les assistants IA.

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.

Les capacités d'écriture ajoutées dans WPForms 1.10.2 appliquent le même modèle de capacités. wpforms/create-form nécessite la capacité de créer des formulaires, et wpforms/add-field, wpforms/update-field et wpforms/update-form-settings nécessitent la capacité de modifier le formulaire cible. Un contrôle échoué renvoie une WP_Error avec le statut HTTP 403. Les capacités d'écriture nécessitent également que l'accès en écriture soit activé, comme décrit ci-dessus.

Référence de capacité

Les capacités de lecture sont idempotentes et peuvent être appelées de manière répétée sans risque. Les capacités d'écriture, ajoutées dans WPForms 1.10.2, créent ou modifient des données de formulaire et nécessitent que l'accès en écriture soit d'abord activé. 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
}

Les capacités ci-dessous ont été ajoutées dans WPForms 1.10.2. Toutes nécessitent que l'accès en écriture soit activé (voir Activation de l'accès en écriture), à l'exception de wpforms/describe-editing-schema, qui est une capacité de lecture utilisée pour découvrir ce que les capacités d'écriture acceptent. Les capacités d'écriture s'exécutent en tant que requêtes POST sur REST, ou via execute() en PHP.

wpforms/schema-de-modification

Renvoie les types de champs et les paramètres de formulaire que les capacités d'écriture acceptent sur ce site. Appelez ceci d'abord, car les types de champs disponibles dépendent du niveau de licence. Disponible en Lite et Pro.

Exemple de requête

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

Exemple de réponse (tronqué)

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

Sur Pro, field_types liste text, textarea, email, number, select, radio, checkbox, name, phone, date-time et file-upload. Sur Lite, l'ensemble est les huit de base : text, textarea, email, number, select, radio, checkbox et name. Les slugs correspondent au constructeur, donc le champ Dropdown est select et le champ Date / Time est date-time.

Propriétés du champ

Les capacités create-form, add-field et update-field acceptent ces propriétés de champ. Chaque propriété s'applique uniquement aux types de champs qui la déclarent, comme indiqué par describe-editing-schema.

wpforms/créer-un-formulaire

Créez un nouveau formulaire avec un ensemble facultatif de champs et de paramètres, en un seul appel. Disponible en Lite et Pro.

Paramètres

Exemple de requête

$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',
        ],
    ]
);

Exemple de réponse

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

wpforms/ajouter-un-champ

Ajoute un nouveau champ à un formulaire existant. Disponible en Lite et Pro.

Paramètres

Passez toutes les propriétés de champ pour le type choisi, en plus de form_id et type (voir le tableau des propriétés de champ ci-dessus).

Exemple de requête

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

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

Exemple de réponse

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

wpforms/mettre-a-jour-un-champ

Met à jour les propriétés d'un champ existant. Disponible en Lite et Pro.

Paramètres

Passez les propriétés du champ que vous souhaitez modifier, en plus de form_id et field_id (voir le tableau des propriétés de champ ci-dessus). Les propriétés que vous omettez restent inchangées. Lorsque vous envoyez choices, la nouvelle liste est fusionnée par index sur les choix existants.

Exemple de requête

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

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

Exemple de réponse

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

wpforms/mettre-a-jour-les-parametres-du-formulaire

Met à jour les paramètres sécurisés d'un formulaire. La liste blanche v1 est form_title, form_desc et submit_text. Disponible en Lite et Pro.

Paramètres

Exemple de requête

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

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

Exemple de réponse

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

Les clés qui ne sont pas dans la liste blanche sont retournées dans le tableau ignored plutôt que de provoquer une erreur. Par exemple, envoyer ajax_submit le laisse inchangé et le liste sous ignored.

Utilisation de WPForms avec les clients MCP

Les capacités de lecture sont enregistrées avec mcp.public défini sur true, de sorte que les clients IA compatibles avec MCP (Claude Desktop, Cursor, et autres) les découvrent automatiquement une fois que le site WordPress est connecté via le plugin wordpress/mcp-adapter. Les capacités d'écriture et wpforms/describe-editing-schema sont exposées à MCP uniquement lorsque l'accès en écriture est activé ; lorsque les écritures sont désactivées, leur indicateur mcp.public est false et elles sont masquées de la découverte MCP, de sorte qu'un assistant peut signaler qu'il ne trouve pas les outils d'écriture WPForms. Une fois qu'un site est connecté et que l'accès en écriture est activé, les capacités apparaissent dans la liste des outils du client sous la catégorie WPForms et respectent les mêmes rappels d'autorisation 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.

Les capacités d'écriture apparaissent dans cet index sur tout site exécutant WPForms 1.10.2 ou une version ultérieure, que l'accès en écriture soit activé ou non. Leur indicateur mcp.public reflète cependant l'état de l'accès en écriture : il est true uniquement lorsque les écritures sont activées, c'est pourquoi les clients MCP ne voient les outils d'écriture qu'après l'activation de l'accès en écriture.

Extension du registre de champs

Les types de champs et les propriétés que les capacités d'écriture acceptent sont définis dans un registre extensible. Les modules complémentaires peuvent enregistrer leurs propres types et propriétés de champs via deux filtres, de sorte qu'un type de champ personnalisé ou de module complémentaire peut devenir disponible pour create-form, add-field et update-field.

• wpforms_integrations_abilities_field_registry_types enregistre de nouveaux types de champs. Chaque type déclare sa disponibilité via une valeur requires, qui est la chaîne pro, un slug de module complémentaire ou un appelable, et peut spécifier ses propriétés requises.
• wpforms_integrations_abilities_field_registry_properties contribue de nouvelles définitions de propriétés que les types de champs peuvent référencer.

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

Liens connexes

• Utilisation de WPForms avec des assistants IA, le guide sans code pour connecter un assistant IA
• Introduction à l'API des capacités WordPress (developer.wordpress.org)
• wordpress/mcp-adapter sur GitHub
• Protocole de contexte de modèle