Referência da API REST do WPForms e da API de Habilidades

O WPForms 1.9.9 introduziu uma API REST somente leitura, construída sobre a API de Habilidades do WordPress. Você pode listar formulários, buscar a configuração do formulário, recuperar e pesquisar entradas, e extrair estatísticas do formulário de qualquer cliente HTTP, linha de comando, seu próprio código PHP ou assistentes de IA que falem o Protocolo de Contexto do Modelo (MCP).

Se você pesquisou por “WPForms REST API” e chegou aqui, é isso. Não há uma API REST separada; a integração com a API de Habilidades é como o WPForms expõe seus dados via HTTP.

O que é a API de Habilidades

A API de Habilidades é um recurso principal do WordPress adicionado no WordPress 6.9. Ela permite que plugins declarem capacidades individuais (chamadas de habilidades) com um nome, um esquema de entrada, um esquema de saída e uma função de callback de permissão. O WordPress então expõe automaticamente cada habilidade registrada via API REST em /wp-json/wp-abilities/v1/abilities/<ability>/run e para clientes de IA compatíveis com MCP através do plugin oficial de adaptador MCP.

O WPForms registra um conjunto de habilidades somente leitura sob o namespace wpforms/. Cada habilidade executa as mesmas verificações de capacidade do WPForms usadas no admin (wpforms_current_user_can()), então as superfícies REST e MCP herdam o modelo de permissão existente em vez de introduzir um novo.

Chamando uma Habilidade

Cada habilidade pode ser invocada através de dois transportes. O resultado é idêntico; escolha o que melhor se adapta ao ambiente de chamada.

API REST

Envie uma requisição GET autenticada para /wp-json/wp-abilities/v1/abilities/<ability>/run. Como toda habilidade do WPForms é somente leitura, apenas GET é aceito; POST retorna 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

De qualquer plugin, tema ou código personalizado que seja executado após a ação wp_abilities_api_init ter disparado, busque a habilidade com wp_get_ability() e chame seu método execute(). Passe a entrada como um array associativo de parâmetros (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 usa autenticação padrão do WordPress. O método recomendado para clientes externos são as Senhas de Aplicativo, que são integradas ao core do WordPress e não exigem nenhum plugin adicional.

Gerando uma Senha de Aplicativo

1. Faça login como o usuário do WordPress cujas permissões as chamadas devem ser executadas.
2. Vá para Usuários » Perfil e role até a seção Senhas de Aplicativo.
3. Insira um nome para a integração e clique em Adicionar nova senha de aplicativo.
4. Copie a senha gerada. O WordPress a exibe apenas uma vez.

Para uma referência mais detalhada, incluindo endpoints REST para gerenciar senhas de aplicativo programaticamente, consulte o Guia de Integração de Senhas de Aplicativo da equipe principal do WordPress.

Enviando as Credenciais

Passe o nome de usuário e a senha do aplicativo como autenticação HTTP Basic em cada solicitação.

Com curl

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

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

Em seguida, adicione o sinalizador -u a cada comando curl. O valor do sinalizador é seu nome de usuário, seguido por dois pontos, seguido por sua senha de aplicativo (sem espaços).

Com Postman, Insomnia ou outros clientes

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

Definindo o cabeçalho manualmente

Envie suas credenciais como um cabeçalho Authorization codificado em base64:

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

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

Permissões

Cada habilidade verifica uma capacidade específica do WPForms antes de executar. Verificações falhas retornam um WP_Error com o status HTTP 403.

Referência de Habilidade

Todas as habilidades são somente leitura e idempotentes. Erros são retornados como objetos WP_Error serializados para JSON com os campos code, message e data.status.

wpforms/list-forms

Lista formulários com metadados de resumo. Disponível no 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

Recupera um único formulário, incluindo um subconjunto selecionado de suas configurações e, opcionalmente, sua configuração de campo. Disponível no 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 objeto settings retornado por esta habilidade é um subconjunto selecionado e não sensível (título, descrição, texto de envio, flag de envio AJAX, honeypot, anti-spam). As configurações de notificação, confirmação e integração não são expostas.

wpforms/get-form-stats

Retorna estatísticas de envio para um formulário. A forma da resposta difere entre 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 Lite

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

Resposta Pro

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

wpforms/get-entry-summaries

Lista paginada de resumos de entradas para um único formulário. Apenas 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

Recupere uma única entrada por ID, incluindo todos os valores de campo. Apenas 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 mascarado. Adicione add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) ao código do seu site; quando ativado, os endereços IPv4 aparecem com seus últimos três octetos substituídos por asteriscos (por exemplo, ***.***.***.100).

wpforms/search-entries

Pesquise entradas em um ou todos os formulários com filtros de texto completo, específicos de campo, status e intervalo de datas. Apenas 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
}

Usando WPForms com Clientes MCP

Toda habilidade do WPForms é registrada com mcp.public definido como true, o que significa que clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) as descobrem automaticamente assim que o site WordPress é conectado através do plugin wordpress/mcp-adapter. Após a instalação, nenhuma configuração adicional do lado do WPForms é necessária; as habilidades aparecem na lista de ferramentas do cliente sob a categoria WPForms e respeitam os mesmos callbacks de permissão usados pela API REST.

Descobrindo Habilidades Programaticamente

Para enumerar as habilidades disponíveis em um site em vez de codificar seus IDs:

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

A resposta inclui o ID, rótulo, descrição, categoria e os esquemas completos de entrada e saída de cada habilidade, o que é informação suficiente para construir um cliente genérico sem conhecimento prévio da superfície específica do WPForms.

Links Relacionados

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