Referência da API REST do WPForms e da API do Abilities

A versão 1.9.9 do WPForms introduziu uma API REST somente leitura baseada na API Abilities do WordPress. Você pode listar formulários, obter configurações de formulários, recuperar e pesquisar entradas, bem como extrair estatísticas de formulários a partir de qualquer cliente HTTP, da linha de comando, do seu próprio código PHP ou de assistentes de IA que utilizem o Protocolo de Contexto de Modelo (MCP).

Se você pesquisou por “WPForms REST API” e chegou até aqui, é isso mesmo. Não existe uma API REST separada; a integração com a API do Abilities é a forma como o WPForms expõe seus dados via HTTP.

O que é a API Abilities

A API de Capacidades é um recurso do núcleo do WordPress adicionado na versão 6.9. Ela permite que os plugins declarem capacidades individuais (chamadas habilidades) com um nome, um esquema de entrada, um esquema de saída e uma função de retorno de permissão. O WordPress, então, expõe automaticamente todas as capacidades registradas por meio da API REST em /wp-json/wp-abilities/v1/abilities/<ability>/run e para clientes de IA compatíveis com o MCP por meio do plugin adaptador oficial do MCP.

O WPForms registra um conjunto de permissões somente leitura sob o wpforms/ namespace. Cada função executa as mesmas verificações de permissão do WPForms utilizadas no painel de administração (wpforms_current_user_can()), de modo que as interfaces REST e MCP herdam o modelo de permissões existente, em vez de introduzirem um novo.

Ativando uma habilidade

Cada função pode ser chamada por meio de dois métodos. O resultado é o mesmo; escolha aquele que for mais adequado ao ambiente de execução.

API REST

Enviar um GET solicitar /wp-json/wp-abilities/v1/abilities/<ability>/run. Como todas as funcionalidades do WPForms são somente de leitura, apenas GET é aceito; POST retornos 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

A partir de qualquer plugin, tema ou código personalizado que seja executado após o wp_abilities_api_init A ação foi disparada; recupere a habilidade com wp_get_ability() e chamar de execute() método. Passe a entrada como uma matriz associativa de parâmetros (com os mesmos nomes listados na tabela de parâmetros de cada habilidade).

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

Autenticação

O transporte REST utiliza a autenticação padrão do WordPress. O método recomendado para clientes externos são as senhas de aplicativo, que estão integradas ao núcleo do WordPress e não exigem nenhum plugin adicional.

Gerando uma senha de aplicativo

1. Faça login como o usuário do WordPress com as permissões sob as quais as chamadas devem ser executadas.
2. Vá para Usuários » Perfil e role a página até a seção Senhas de aplicativos.
3. Digite um nome para a integração e clique em “Adicionar nova senha de aplicativo”.
4. Copie a senha gerada. O WordPress só a exibe uma vez.

Para obter mais informações, incluindo pontos de extremidade REST para gerenciar senhas de aplicativos programaticamente, consulte o Guia de integração de senhas de aplicativos da equipe principal do WordPress.

Envio das credenciais

Envie o nome de usuário e a senha do aplicativo como autenticação HTTP básica em todas as solicitações.

Com o curl

Defina a URL do seu site como uma variável de ambiente para que os exemplos deste documento possam ser executados tal como estão:

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

Em seguida, adicione o -u Adicione essa opção a todos os comandos do curl. O valor da opção é o seu nome de usuário, seguido de dois pontos e, em seguida, da senha do seu aplicativo (sem espaços).

Com o Postman, o Insomnia ou outros clientes

Defina o tipo de autenticação da solicitação como "Basic Auth " e forneça seu nome de usuário e senha do aplicativo. O cliente se encarrega da codificação para você.

Definir o cabeçalho manualmente

Envie suas credenciais codificadas em base64 Authorization cabeçalho:

Combine seu nome de usuário e sua senha do aplicativo em uma única sequência, separados por dois pontos (sem espaços), e codifique o resultado em base64 usando uma ferramenta de sua escolha (base64 comando, um codificador online ou a biblioteca padrão da sua linguagem). Envie o valor codificado em cada solicitação como o Authorization cabeçalho, no formato Authorization: Basic <encoded>.

Os exemplos de solicitação apresentados no restante deste documento omitem o sinalizador de autenticação para facilitar a leitura. Adicione o -u sinalizador (ou o Authorization (cabeçalho) a cada solicitação real, ou a API retorna 401 Unauthorized.

Permissões

Cada função verifica uma funcionalidade específica do WPForms antes de ser executada. Se a verificação falhar, ela retorna um WP_Error com código de status HTTP 403.

Referência de habilidades

Todas as funções são somente de leitura e idempotentes. Os erros são retornados como WP_Error objetos serializados para JSON com code, messagee data.status campos.

wpforms/lista-de-formulários

Formulários de lista com metadados resumidos. Disponível nas versões Lite e Pro.

Parâmetros

Exemplo de solicitação

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

Exemplo de resposta

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

Recuperar um único formulário, incluindo um subconjunto selecionado de suas configurações e, opcionalmente, a configuração de seus campos. Disponível nas versões Lite e Pro.

Parâmetros

Exemplo de solicitação

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

Exemplo de resposta

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

O settings O objeto retornado por esta funcionalidade é um subconjunto selecionado e não confidencial (título, descrição, texto de envio, sinalizador de envio AJAX, honeypot, antispam). As configurações de notificação, confirmação e integração não são expostas.

wpforms/obter-estatísticas-do-formulário

Exibe as estatísticas de envio de um formulário. O formato da resposta difere entre as versões Lite e Pro.

Parâmetros

Exemplo de solicitação

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

Resposta simplificada

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

Resposta profissional

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

wpforms/obter-resumos-das-entradas

Lista paginada de resumos de entradas para um único formulário. Exclusivo da versão Pro.

Parâmetros

Exemplo de solicitação

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"

Exemplo de resposta

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

Recuperar uma única entrada pelo ID, incluindo todos os valores dos campos. Exclusivo da versão Pro.

Parâmetros

Exemplo de solicitação

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

Exemplo de resposta

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

O endereço IP na resposta pode ser ocultado. Adicionar add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) no código do seu site; quando ativada, os endereços IPv4 são exibidos com os três últimos octetos substituídos por asteriscos (por exemplo, ***.***.***.100).

wpforms/pesquisar-entradas

Pesquise entradas em um formulário ou em todos os formulários usando filtros de texto completo, por campo específico, por status e por intervalo de datas. Exclusivo da versão Pro.

Parâmetros

Exemplo de solicitação

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"

Exemplo de resposta

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

Como usar o WPForms com clientes da MCP

Todas as funcionalidades do WPForms estão registradas no mcp.public definir como true, o que significa que os clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) os detectam automaticamente assim que o site do WordPress estiver conectado por meio do wordpress/adaptador-mcp plug-in. Após a instalação, não é necessária nenhuma configuração adicional no WPForms; as funcionalidades aparecem na lista de ferramentas do cliente, na seção WPForms categoria e respeitar os mesmos callbacks de permissão utilizados pela API REST.

Descobrindo habilidades por meio de programação

Para listar as funcionalidades disponíveis em um site, em vez de codificar manualmente seus IDs:

# Listar todas as funcionalidades registradas no site
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Obter o esquema de uma única funcionalidade
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

A resposta inclui o ID, o rótulo, a descrição e a categoria de cada função, além dos esquemas completos de entrada e saída, o que constitui informação suficiente para criar um cliente genérico sem conhecimento prévio da interface específica do WPForms.

Links relacionados

• Apresentando a API de Capacidades do WordPress (developer.wordpress.org)
• wordpress/mcp-adapter no GitHub
• Protocolo de Contexto de Modelo