A WordPress Abilities API é um registo de operações que um plugin, um tema ou o próprio núcleo declara num formato único e previsível: nome, categoria, esquema de entrada e de saída, verificação de permissões e a função que executa. Esta página é uma referência: o que é, como registar uma ability, que endpoints REST existem, como funcionam as permissões, o que trouxeram as versões 7.0 e 7.1 e onde entra o MCP Adapter. Se procura exemplos de fluxos de trabalho construídos sobre abilities, veja o artigo Abilities API na prática, fluxos de IA no WordPress.
O que é a WordPress Abilities API
A dev note publicada em make.wordpress.org define uma ability assim:
“Uma ability é uma unidade de funcionalidade autónoma com entradas, saídas, permissões e lógica de execução definidas.”
Jonathan Bossenger, Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
Todas as abilities registadas vão para um registo central. É desse registo que se servem o código PHP no servidor, o cliente JavaScript no painel de administração, a REST API e os agentes de IA ligados através do MCP Adapter. O plugin descreve a operação uma vez e cada um destes canais vê-a com a mesma forma, o mesmo esquema e a mesma verificação de permissões.
O anúncio do lançamento do 6.9 apresenta a novidade pelo lado das permissões:
“A nova Abilities API oferece um sistema de permissões padronizado e legível por máquinas, que abre a porta a fluxos de trabalho automatizados e com IA da próxima geração.”
WordPress News, WordPress 6.9 “Gene”, tradução própria
Cada ability pertence a exatamente uma categoria:
“Cada ability tem de pertencer exatamente a uma categoria. As categorias têm um slug, uma etiqueta e uma descrição.”
Common APIs Handbook, Abilities API, tradução própria
A partir de que versão do WordPress existe a Abilities API
A Abilities API entrou no núcleo com o WordPress 6.9, lançado a 2 de dezembro de 2025. O Handbook di-lo sem rodeios, num destaque no topo da página:
“A Abilities API só está disponível no WordPress 6.9 e versões posteriores.”
Common APIs Handbook, Abilities API, tradução própria
As versões seguintes alargaram a API sem mexer nas bases:
| Versão | Data | O que trouxe |
|---|---|---|
| 6.9 “Gene” | 2 de dezembro de 2025 | registo, categorias, esquemas, permissões, endpoints wp-abilities/v1 |
| 7.0 | dev note de 24 de março de 2026 | cliente JavaScript: @wordpress/abilities e @wordpress/core-abilities |
| 7.1 “Mary Lou” | 19 de agosto de 2026 | flag meta.public, quatro filtros do ciclo de execução |
Um plugin que também tenha de funcionar em instalações anteriores ao 6.9 verifica se a função existe antes de registar: a dev note em make.wordpress.org recomenda a condição function_exists( 'wp_register_ability' ), que abre também o exemplo mais abaixo.
O contexto mais amplo do lançamento do 7.0, incluindo as restantes novidades ligadas à IA, está no nosso guia do WordPress 7.0 e da integração com IA.
Como registar uma ability no WordPress
O registo tem dois passos: primeiro a categoria, depois a ability. Cada passo tem o seu hook e a ordem conta.
Registar uma categoria de abilities
“As categorias têm de ser registadas antes das abilities que as referenciam, usando o hook wp_abilities_api_categories_init.”
Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
A categoria tem slug, etiqueta e descrição. O argumento category no registo da ability é obrigatório e tem de apontar para o slug de uma categoria que já exista no registo.
Hook wp_abilities_api_init
A ability propriamente dita regista-se numa ação separada. Registá-la noutro sítio não funciona:
“As abilities têm de ser registadas no action hook wp_abilities_api_init. Tentar registar abilities fora deste hook irá gerar um aviso _doing_it_wrong(), e o registo da Ability falhará.”
Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
Exemplo de wp_register_ability
Assinatura da função segundo a Code Reference:
function wp_register_ability( string $name, array $args ): ?WP_Ability {Fonte: Code Reference, wp_register_ability().
Em caso de sucesso, a função devolve a instância WP_Ability registada; em caso de erro, null. Exemplo mínimo: uma categoria e uma única ability só de leitura, que devolve o número de artigos publicados.
if ( function_exists( 'wp_register_ability' ) ) {
add_action( 'wp_abilities_api_categories_init', function () {
wp_register_ability_category( 'meu-plugin', array(
'label' => 'O meu plugin',
'description' => 'Operações disponibilizadas pelo meu plugin.',
) );
} );
add_action( 'wp_abilities_api_init', function () {
wp_register_ability( 'meu-plugin/numero-de-artigos', array(
'label' => 'Número de artigos publicados',
'description' => 'Devolve o número de artigos publicados.',
'category' => 'meu-plugin',
'output_schema' => array( 'type' => 'integer' ),
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'execute_callback' => function () {
return (int) wp_count_posts()->publish;
},
'meta' => array(
'show_in_rest' => true,
'annotations' => array( 'readonly' => true ),
),
) );
} );
}Esta ability não recebe dados, por isso não tem input_schema. Devolve um valor, por isso o output_schema é obrigatório.
Nome da ability e namespace
“The format should be namespace/ability-name”
Make WordPress Core, Abilities API in WordPress 6.9
O nome usa letras minúsculas, algarismos, hífenes e uma barra. O namespace é normalmente o slug do plugin, o que evita colisões entre plugins que registam operações parecidas.
input_schema e output_schema na Abilities API
Os esquemas não são um extra para a documentação. O núcleo usa-os para validar os dados de entrada antes da execução e os dados de saída depois dela.
“Definir schemas é obrigatório quando há um valor a passar ou a devolver.”
Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
O validador não suporta a especificação completa do JSON Schema:
“WordPress implements a validator based on a subset of JSON Schema Version 4.”
Make WordPress Core, Abilities API in WordPress 6.9
Na prática, isto significa escrever os esquemas na sintaxe do draft 4 e ter cuidado com palavras-chave fora desse subconjunto.
permission_callback e execute_callback
Os dois callbacks são obrigatórios. A Code Reference descreve-os assim:
“Obrigatório. Uma função de callback para verificar permissões antes da execução.”
Code Reference, wp_register_ability(), tradução própria
“Obrigatório. Uma função de callback a executar quando a ability é invocada.”
Code Reference, wp_register_ability(), tradução própria
O callback de permissões recebe os mesmos dados que o callback de execução, por isso pode decidir em função da entrada concreta, por exemplo permitir editar apenas um artigo de que o utilizador seja autor:
“Recebe a mesma entrada que o callback de execução e tem de devolver um booleano ou WP_Error”
Code Reference, wp_register_ability(), tradução própria
Tratamento de erros no execute_callback
Um erro devolve-se como objeto, não como exceção nem como resultado vazio:
“As abilities devem tratar os erros de forma controlada, devolvendo objetos WP_Error:”
Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
Anotações readonly, destructive e idempotent
As anotações em meta.annotations descrevem a natureza da operação. readonly marca uma ability que não altera nada:
“Opcional. Se for true, a ability não modifica o seu ambiente.”
Code Reference, wp_register_ability(), tradução própria
As outras duas anotações são destructive e idempotent. Não são decorativas: delas depende o método HTTP numa chamada pela REST API, e um cliente, por exemplo um agente de IA, pode usá-las para avaliar se a operação pode ser repetida.
Este site corre o nosso próprio servidor MCP, descrito em /.well-known/mcp/server-card.json, e expõe apenas ferramentas de leitura. O mesmo princípio funciona bem com abilities: a primeira versão de uma integração com um agente são abilities com readonly: true, chamadas por GET. As operações de escrita vêm depois, cada uma com o seu permission_callback.
Endpoints REST da Abilities API
No WordPress 6.9, uma ability não aparece na REST API automaticamente. É preciso declará-lo:
“Isto é possível definindo o argumento meta.show_in_rest como true ao registar uma ability.”
Make WordPress Core, Abilities API in WordPress 6.9, tradução própria
Os endpoints ficam no namespace wp-abilities/v1: a lista de abilities, uma ability individual e a execução. O caminho de execução é este:
GET|POST|DELETE /wp-abilities/v1/abilities/{name}/runFonte: Make WordPress Core, Abilities API in WordPress 6.9.
Autenticação na Abilities API
“Access to all Abilities REST API endpoints requires an authenticated user.”
Make WordPress Core, Abilities API in WordPress 6.9
Isto vale também para a lista de abilities. Funciona com o cookie de sessão, com application passwords ou com um mecanismo de autenticação próprio. Um cliente anónimo nem sequer consegue ver que abilities existem no site.
Como chamar uma ability pela REST API
O método HTTP do endpoint run é determinado pelas anotações. Uma ability readonly chama-se com GET, uma ability simultaneamente destructive e idempotent com DELETE, e nos restantes casos:
“Todos os outros casos: usa POST”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tradução própria
A documentação REST no repositório do projeto sublinha que, para abilities só de leitura, isto é uma obrigação e não uma recomendação:
”- Read-only abilities must use GET (
readonly: true)”GitHub, WordPress/abilities-api, docs/rest-api.md
Com GET e DELETE, os dados de entrada não vão no corpo do pedido, mas no parâmetro input, como JSON codificado no URL.
Abilities API em JavaScript
O WordPress 7.0 acrescentou um cliente do lado do browser, distribuído por dois pacotes. @wordpress/abilities é o armazenamento de abilities propriamente dito e @wordpress/core-abilities carrega, através da REST API, as abilities registadas no servidor:
“Isto carrega tanto @wordpress/core-abilities como a sua dependência @wordpress/abilities, e obtém e regista automaticamente todas as abilities do lado do servidor.”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tradução própria
Os erros no cliente JS têm códigos fixos. Uma validação falhada dá ability_invalid_input ou ability_invalid_output, e uma recusa de permissões:
“Se o callback de permissões devolver false, é lançado um erro com o código ability_permission_denied.”
Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tradução própria
Abilities API no WordPress 7.1
O anúncio do lançamento do 7.1 resume as alterações numa frase:
“A Abilities API baseia-se na infraestrutura introduzida no WordPress 6.9, com um ciclo de vida de execução filtrável, validação personalizada e descoberta partilhada.”
WordPress News, WordPress 7.1 “Mary Lou”, tradução própria
Flag public na Abilities API
O WordPress 7.1 introduziu meta.public, uma flag comum de exposição aos clientes. Ela preenche show_in_rest, mas um show_in_rest indicado explicitamente tem prioridade, e o valor por omissão continua a ser false:
$show_in_rest = $meta['show_in_rest'] ?? $meta['public'] ?? false;Fonte: Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1.
A flag decide a visibilidade, não o acesso:
“O indicador public controla a possibilidade de descoberta e a exposição a clientes.”
Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1, tradução própria
Uma ability marcada como pública continua a passar pelo permission_callback. A flag public não o substitui.
Filtros do ciclo de execução de uma ability
“A Abilities API disponibilizava anteriormente as actions wp_before_execute_ability e wp_after_execute_ability.”
Make WordPress Core, New execution lifecycle filters for the Abilities API in WordPress 7.1, tradução própria
A estas duas ações do 6.9, a versão 7.1 juntou quatro filtros:
| Filtro | Fase da execução |
|---|---|
wp_pre_execute_ability | antes da execução |
wp_ability_normalize_input | normalização dos dados de entrada |
wp_ability_permission_result | resultado da verificação de permissões |
wp_ability_execute_result | resultado da execução |
As ações só permitiam observar a execução. Os filtros permitem intervir nela, por exemplo normalizar a entrada ou alterar o resultado da verificação de permissões.
Abilities API e MCP Adapter
A Abilities API não inclui um servidor Model Context Protocol. Esse papel cabe a um pacote separado:
“O pacote oficial do WordPress para integração MCP, que expõe as abilities do WordPress como ferramentas, recursos e prompts do Model Context Protocol (MCP) para agentes de IA.”
GitHub, WordPress/mcp-adapter, README, tradução própria
A configuração por omissão é conservadora:
“As abilities do WordPress são privadas por omissão.”
GitHub, WordPress/mcp-adapter, README, tradução própria
Para uma ability ficar visível a um cliente MCP, é preciso definir meta.public (ou meta.mcp.public) como true. O servidor por omissão do adaptador expõe três meta-ferramentas, através das quais o agente descobre e chama as abilities. A ligação:
“Connect via WP-CLI over STDIO, or point an HTTP client at
/wp-json/mcp/mcp-adapter-default-server.”GitHub, WordPress/mcp-adapter, README
STDIO através do WP-CLI serve para trabalho local e em staging; HTTP serve para um agente que corre fora do servidor. Em ambos os casos, o que o agente pode fazer é decidido pelos mesmos permission_callback e pelas mesmas anotações descritos acima.
Explicamos com mais detalhe como ligar o WordPress a agentes de IA via MCP no guia de integração MCP com IA no WordPress. Se precisa de um servidor MCP próprio ou de um conjunto de abilities pensado para uma loja ou um site concreto, descrevemos esse trabalho na página desenvolvimento de servidores MCP para WordPress.
Como saber se o WordPress suporta a Abilities API
A forma mais simples é no código: function_exists( 'wp_register_ability' ) devolve true a partir da versão 6.9. Do exterior, com uma conta que tenha uma application password, basta consultar o namespace wp-abilities/v1 na REST API do site. Se não existir, o site está numa versão anterior ao 6.9 ou há algo a bloquear a REST API. A lista só devolve abilities com show_in_rest ou public definido como true, por isso uma lista vazia não significa que os plugins não registem nenhuma ability.
Última verificação das fontes: 6 de outubro de 2026.
