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

WPForms 1.9.9 introduziu uma API REST construída sobre a WordPress Abilities API, e o WPForms 1.10.2 a expandiu com suporte de escrita opcional. Você pode listar formulários, buscar a configuração do formulário, recuperar e pesquisar entradas, e obter estatísticas do formulário, e, uma vez habilitado o acesso de escrita, criar formulários, adicionar e atualizar campos, e atualizar configurações seguras do formulário. Cada habilidade funciona a partir de qualquer cliente HTTP, linha de comando, seu próprio código PHP, ou assistentes de IA que falam o Model Context Protocol (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.

WPForms registra um conjunto de habilidades sob o namespace wpforms/. As habilidades de leitura estão disponíveis desde o WPForms 1.9.9. O WPForms 1.10.2 adicionou um conjunto de habilidades de escrita que estão desabilitadas por padrão (veja Habilitando Acesso de Escrita abaixo). 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 solicitação autenticada para /wp-json/wp-abilities/v1/abilities/<ability>/run. O método HTTP depende da habilidade: habilidades de leitura usam GET, e habilidades de escrita usam POST. Chamar uma habilidade com o método errado 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.

Habilitando Acesso de Escrita

As habilidades de leitura estão sempre disponíveis. As habilidades de escrita (wpforms/create-form, wpforms/add-field, wpforms/update-field e wpforms/update-form-settings) estão desabilitadas por padrão e devem ser ativadas antes de serem executadas. Existem duas maneiras de habilitá-las, e o filtro sempre terá a palavra final.

Habilitando Escritas em Código

Habilite escritas programaticamente com o filtro wpforms_integrations_abilities_allow_write:

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

O filtro substitui a opção sem código em ambas as direções. Retornar true habilita escritas mesmo quando a opção está desativada, e retornar false as desabilita mesmo quando a opção está ativada. Isso mantém as configurações existentes do desenvolvedor funcionando sem alterações.

Habilitando Escritas Sem Código

Os proprietários do site podem habilitar gravações em WPForms » Ferramentas » AI MCP com a chave Habilitar Acesso de Gravação MCP, que persiste na chave ai-mcp-write-enabled na opção wpforms_settings. O filtro acima tem precedência sobre esta chave. Para o guia completo, veja Usando WPForms com Assistentes de IA.

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.

As habilidades de gravação adicionadas no WPForms 1.10.2 aplicam o mesmo modelo de capacidade. wpforms/create-form requer a capacidade de criar formulários, e wpforms/add-field, wpforms/update-field e wpforms/update-form-settings requerem a capacidade de editar o formulário de destino. Uma verificação falha retorna um WP_Error com o status HTTP 403. As habilidades de gravação também exigem que o acesso de gravação esteja habilitado, conforme descrito acima.

Referência de Habilidade

As habilidades de leitura são idempotentes e seguras para serem chamadas repetidamente. As habilidades de gravação, adicionadas no WPForms 1.10.2, criam ou modificam dados de formulário e exigem que o acesso de gravação seja habilitado primeiro. 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
}

As habilidades abaixo foram adicionadas no WPForms 1.10.2. Todas elas exigem que o acesso de gravação esteja habilitado (veja Habilitando Acesso de Gravação), exceto wpforms/describe-editing-schema, que é uma habilidade de leitura usada para descobrir o que as habilidades de gravação aceitam. As habilidades de gravação são executadas como requisições POST via REST, ou através de execute() em PHP.

wpforms/describe-editing-schema

Retorna os tipos de campo e as configurações de formulário que as habilidades de gravação aceitam neste site. Chame esta primeiro, pois os tipos de campo disponíveis dependem do nível da licença. Disponível em Lite e Pro.

Exemplo de Solicitação

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

Exemplo de Resposta (truncado)

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

No Pro, field_types lista text, textarea, email, number, select, radio, checkbox, name, phone, date-time e file-upload. No Lite, o conjunto é o básico de oito: text, textarea, email, number, select, radio, checkbox e name. Os slugs correspondem ao construtor, então o campo Dropdown é select e o campo Date / Time é date-time.

Propriedades do Campo

As habilidades create-form, add-field e update-field aceitam essas propriedades de campo. Cada propriedade se aplica apenas aos tipos de campo que a declaram, conforme relatado por describe-editing-schema.

wpforms/criar-formulario

Crie um novo formulário com um conjunto opcional de campos e configurações, em uma única chamada. Disponível no Lite e Pro.

Parâmetros

Exemplo de Solicitação

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

Exemplo de Resposta

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

wpforms/adicionar-campo

Adicione um novo campo a um formulário existente. Disponível no Lite e Pro.

Parâmetros

Passe quaisquer propriedades de campo para o tipo escolhido ao lado de form_id e type (consulte a tabela de Propriedades de Campo acima).

Exemplo de Solicitação

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

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

Exemplo de Resposta

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

wpforms/atualizar-campo

Atualize as propriedades de um campo existente. Disponível no Lite e Pro.

Parâmetros

Passe as propriedades do campo que você deseja alterar ao lado de form_id e field_id (consulte a tabela de Propriedades de Campo acima). As propriedades que você omitir permanecerão inalteradas. Ao enviar choices, a nova lista é mesclada por índice sobre as escolhas existentes.

Exemplo de Solicitação

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

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

Exemplo de Resposta

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

wpforms/atualizar-configuracoes-formulario

Atualize as configurações seguras de um formulário. A lista de permissões v1 é form_title, form_desc e submit_text. Disponível no Lite e Pro.

Parâmetros

Exemplo de Solicitação

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

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

Exemplo de Resposta

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

Chaves que não estão na lista de permissões são retornadas na matriz ignored em vez de causar um erro. Por exemplo, enviar ajax_submit o deixa inalterado e o lista em ignored.

Usando WPForms com Clientes MCP

As habilidades de leitura são registradas com mcp.public definido como true, para que clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) as descubram automaticamente assim que o site WordPress for conectado através do plugin wordpress/mcp-adapter. As habilidades de escrita e wpforms/describe-editing-schema são expostas ao MCP apenas quando o acesso de escrita está habilitado; enquanto as escritas estão desativadas, sua flag mcp.public é false e elas são ocultadas da descoberta do MCP, então um assistente pode relatar que não consegue encontrar as ferramentas de escrita do WPForms. Uma vez que um site é conectado e o acesso de escrita está ativado, 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.

As habilidades de escrita aparecem neste índice em qualquer site executando WPForms 1.10.2 ou posterior, independentemente de o acesso de escrita estar habilitado ou não. Sua flag mcp.public reflete o estado do acesso de escrita, no entanto: é true apenas quando as escritas estão habilitadas, que é o motivo pelo qual os clientes MCP veem as ferramentas de escrita apenas após o acesso de escrita ser ativado.

Estendendo o Registro de Campos

Os tipos de campo e propriedades que as habilidades de escrita aceitam são definidos em um registro extensível. Addons podem registrar seus próprios tipos de campo e propriedades através de dois filtros, então um tipo de campo personalizado ou de addon pode se tornar disponível para create-form, add-field e update-field.

• wpforms_integrations_abilities_field_registry_types registra novos tipos de campo. Cada tipo declara sua disponibilidade através de um valor requires, que é a string pro, um slug de addon ou um callable, e pode especificar suas propriedades necessárias.
• wpforms_integrations_abilities_field_registry_properties contribui com novas definições de propriedade que os tipos de campo podem referenciar.

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

Links Relacionados

• Usando WPForms Com Assistentes de IA, o guia sem código para conectar um assistente de IA
• Apresentando a API de Habilidades do WordPress (developer.wordpress.org)
• wordpress/mcp-adapter no GitHub
• Protocolo de Contexto do Modelo