Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Use the WordPress Abilities API

Short answer

To use the WordPress Abilities API, update to WordPress 6.9 or newer, register a category on the wp_abilities_api_categories_init hook, then register an ability on wp_abilities_api_init with a namespaced name, JSON schemas, an execute callback, and a permission callback. Run it from PHP with wp_get_ability() and execute(), or expose it through the REST API by setting show_in_rest to true.

Key takeaways

  • The Abilities API is only available in WordPress 6.9 and above, released on December 2, 2025.
  • Every ability needs exactly one category, registered before the ability that names it.
  • Register abilities only on the wp_abilities_api_init hook, or registration fails.
  • Abilities stay hidden from the REST API unless show_in_rest is set to true.
  • WordPress 6.9 ships with 3 read-only core abilities for site, user, and environment facts.
  • Every REST call needs an authenticated user, and each ability runs its own permission callback.

What is the WordPress Abilities API?

The WordPress Abilities API is a core registry where plugins, themes, and WordPress itself describe one task, with its inputs, outputs, and permission check.

An ability is a self-contained unit of functionality with defined inputs, outputs, permissions, and execution logic. That definition comes from the Make WordPress Core dev note for WordPress 6.9, which introduced the API as a standard, machine-readable format for site features.

The Abilities API handbook adds that each ability has a label, a description, input and output definitions using JSON Schema, one category, and an execute callback.

The registry is the key idea. Before this API, a feature often lived only inside one plugin, behind its own function or AJAX handler. Now it sits in one central list, the WP_Abilities_Registry, where other code can look it up by name and run it the same way every time.

PartWhat it isExample
AbilityOne task with a name, schemas, and callbacksmy-plugin/get-post-count
CategoryA group that organises related abilitiescontent-management
RegistryThe central list that holds all abilitiesWP_Abilities_Registry
Execute callbackThe PHP function that does the workmy_plugin_get_post_count
Permission callbackThe check that decides who can run itcurrent_user_can( 'read' )

What do you need before you start using the Abilities API?

You need WordPress 6.9 or newer, an administrator account, a backup, and basic PHP knowledge.

The handbook states plainly that the Abilities API is only available for WordPress 6.9 and above. WordPress 6.9, code-named “Gene”, was released on December 2, 2025, according to the official release announcement on WordPress.org.

Check your version first. Go to “Dashboard → Updates” in your admin area and confirm the installed version is 6.9 or newer. If it is older, update WordPress before you write any ability code, since the registration functions will not exist.

You also need these items:

  • An administrator account, so you can add code and change settings.
  • A staging site or a full backup, so a code error cannot break your live site. Follow the guide to back up WordPress before you start.
  • A code editor and a way to add PHP, such as a small custom plugin or a child theme.
  • Basic PHP knowledge, including functions, arrays, and hooks.

The whole first ability takes about 30 to 60 minutes if you already know PHP.

How do you register your first ability?

You register a category first, then register the ability on its own hook with a name, schemas, and callbacks.

Registration has 3 stages: register a category, register the ability, then add the function that does the work. Categories come first, because every ability must belong to exactly one category, and the category must exist before the ability that names it.

Follow these steps in order:

  1. Create a small custom plugin file, or open your child theme's functions.php file.
  2. Hook a category function to wp_abilities_api_categories_init and call wp_register_ability_category() with a slug, a label, and a description.
  3. Hook an ability function to wp_abilities_api_init and call wp_register_ability() with a namespaced name such as my-plugin/get-post-count.
  4. Add a label and a description that explain the task in plain words.
  5. Add an input_schema and an output_schema using JSON Schema, so WordPress can check the data.
  6. Add an execute_callback with the function that does the work, and a permission_callback that checks the user.
  7. Activate the plugin, or save the theme file, then check that the ability is listed.

Here is a short example based on the official handbook. It registers a category, then a read-only ability that returns site facts:

add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_category' );

function my_plugin_register_category() {
    wp_register_ability_category(
        'site-information',
        array(
            'label'       => __( 'Site Information', 'my-plugin' ),
            'description' => __( 'Abilities that provide information about the site.', 'my-plugin' ),
        )
    );
}

add_action( 'wp_abilities_api_init', 'my_plugin_register_ability' );

function my_plugin_register_ability() {
    wp_register_ability(
        'my-plugin/site-info',
        array(
            'label'               => __( 'Site Info', 'my-plugin' ),
            'description'         => __( 'Returns information about this WordPress site.', 'my-plugin' ),
            'category'            => 'site-information',
            'input_schema'        => array(),
            'output_schema'       => array(
                'type'       => 'object',
                'properties' => array(
                    'site_name' => array( 'type' => 'string' ),
                    'site_url'  => array( 'type' => 'string' ),
                ),
            ),
            'execute_callback'    => 'my_plugin_get_site_info',
            'permission_callback' => function() {
                return current_user_can( 'manage_options' );
            },
            'meta'                => array( 'show_in_rest' => true ),
        )
    );
}

The official example then returns the site name, URL, active theme, active plugins, PHP version, and WordPress version from its execute callback. Keep your first ability read-only like this one, so a mistake cannot change or delete content.

How do you organise abilities into categories?

Every ability belongs to exactly one category, which you must register before the ability that names it.

Categories exist so related abilities stay together and are easy to find. The handbook states that each ability must belong to exactly one category, and each category has a slug, a label, and a description.

Register categories on the wp_abilities_api_categories_init hook, and abilities on the wp_abilities_api_init hook.

The order matters: the category hook fires first, so the category exists by the time your ability names it. If you register the ability first, or skip the category step, the ability cannot attach to a category that does not exist yet.

Use short, clear slugs. A store plugin might use orders, products, and customers as 3 separate categories.

A reporting plugin might use one category, reports, for all of its abilities. Pick names that match what the ability does, not your company name, so other developers and AI tools can guess the group.

WordPress ships 5 category functions in the PHP API, listed in the Make WordPress Core dev note. Use wp_register_ability_category() to add one, wp_get_ability_categories() to list them, and wp_has_ability_category() to check whether a slug already exists.

How do you run an ability from PHP?

You fetch the ability by name with wp_get_ability(), then call execute() on it.

The Make WordPress Core dev note shows this pattern. It runs during the init action or any action after it, once the registry is loaded.

add_action( 'init', 'my_plugin_run_ability' );

function my_plugin_run_ability() {
    $ability = wp_get_ability( 'my-plugin/get-post-count' );

    if ( ! $ability ) {
        return;
    }

    $result = $ability->execute();
}

Always check the result before you use it. The handbook's getting-started page shows the result checked with is_wp_error().

A failed run returns a WP_Error object instead of your expected value. Log the error message with $result->get_error_message() and stop, rather than passing a bad value to the next step.

Use wp_has_ability() first when you are not sure the ability exists. It returns true or false for a name, so you can skip the call on sites where the plugin that registered it is turned off.

Use wp_get_abilities() when you need the full list, for example to build an admin screen that shows every ability on the site.

How do you expose an ability through the REST API?

You expose an ability through REST by setting show_in_rest to true when you register it.

By default, registered abilities are not exposed via the REST API, according to the REST endpoints page in the developer handbook.

The endpoints live under the /wp-abilities/v1 namespace. The Make WordPress Core dev note lists 5 routes, and the handbook documents each one with its parameters.

EndpointMethodWhat it does
/wp-abilities/v1/abilitiesGETLists all abilities exposed through REST
/wp-abilities/v1/abilities/{name}GETShows one ability by its namespaced name
/wp-abilities/v1/abilities/{name}/runGET, POST, or DELETERuns one ability
/wp-abilities/v1/categoriesGETLists all ability categories
/wp-abilities/v1/categories/{slug}GETShows one category by slug

The HTTP method for the run endpoint depends on what the ability does. Read-only abilities must use GET, regular abilities use POST when they need input, and destructive abilities must use DELETE, as the handbook explains.

This keeps safe reads on GET and destructive work on DELETE, so a cached GET request cannot delete content by accident.

List requests accept paging. The page parameter defaults to 1, per_page defaults to 50 with a maximum of 100, and category filters the list by category slug. Set per_page to 100 when you want the full list in one call on a site with many abilities.

How do you check that your ability worked?

You check an ability in PHP first, then through the REST list, then through the run endpoint.

Start with PHP, since it shows whether registration worked at all, then move to REST to confirm the public side.

  1. Call wp_has_ability( 'my-plugin/site-info' ) from your code. If it returns false, registration failed or the hook did not run.
  2. Open the REST list with an authenticated request and look for your ability name in the JSON. Use an application password for the request, as the handbook recommends application passwords for external access.
  3. Run the ability through the /run endpoint and compare the JSON reply with your output schema.
  4. Read the error code if the call fails, and match it to the list below.
Error codeWhat it means
ability_missing_input_schemaThe ability needs input, but none was given
ability_invalid_inputThe input failed the schema check
ability_invalid_permissionsThe current user may not run this ability
ability_invalid_outputThe result failed the output schema check
ability_invalid_execute_callbackThe execute callback cannot be called
rest_ability_not_foundThe ability is not registered, or is hidden from REST
rest_ability_category_not_foundThe category is not registered

A rest_ability_not_found error on an ability you just registered usually means show_in_rest is still false.

An ability_invalid_permissions error means the permission callback returned false for that user, so sign in as a user with the right role and try again.

If PHP cannot find the ability at all, check that you hooked registration to wp_abilities_api_init and not to init or plugins_loaded. For a wider look at error hunting, see the guide on how to use AI to fix WordPress errors.

How do permissions keep your abilities safe?

Permissions keep abilities safe because every REST call needs an authenticated user and each ability runs its own permission callback.

The handbook states that access to all Abilities REST API endpoints requires an authenticated user. Access to run one ability is restricted by that ability's permission_callback().

Use a real capability check in the callback, not a blanket yes. The official examples use current_user_can( 'manage_options' ) for site facts, current_user_can( 'read' ) for a post count, and current_user_can( 'edit_posts' ) for a text task.

Match the check to the risk: a read-only fact can allow a lower capability, while anything that writes, deletes, or changes settings needs a higher one.

The handbook lists 3 ways to authenticate REST calls: cookie authentication for same-origin requests, application passwords, and custom authentication plugins.

Application passwords are recommended for external access. Create one under “Users → Profile → Application Passwords” for each outside tool, and give each tool its own password so you can revoke one without breaking the others.

Never leave a write ability open to every user. The getting-started page shows __return_true as a permission callback for one read-only example that returns only the public site title. That pattern is fine for public facts, but it is the wrong choice for an ability that creates posts, changes options, or moves money.

What can you build with the Abilities API?

You can build read-only site tools, plugin features, and AI-connected tasks on top of registered abilities.

WordPress 6.9 ships with 3 read-only core abilities, according to the developer blog post that introduced the MCP Adapter. They are core/get-site-info, which returns site facts, core/get-user-info, which returns basic profile details for the current user, and core/get-environment-info, which returns runtime facts such as the environment type, PHP version, and database server.

Those 3 are a starting point, not a limit. Plugins can add abilities for their own features, such as listing orders, creating a draft post, or running a site check.

Once registered, the same ability can be called from PHP, from the REST API, and from an AI agent, without writing a separate endpoint for each caller.

The MCP Adapter connects abilities to AI tools. It is an official package in the AI Building Blocks initiative.

The developer blog says it lets AI tools such as Claude Desktop, Claude Code, Cursor, and VS Code discover and call WordPress abilities directly as MCP tools. Read the guide to WordPress AI features before you expose tasks to an agent.

Good first abilities are small and read-only: a post count, a list of recent orders, or a site health summary.

Save write abilities, such as creating posts or updating settings, until the read-only ones work and their permission checks are proven. For ideas on pairing abilities with a chat interface, see the guide on how to add an AI chatbot to WordPress.

What mistakes should you avoid?

The most common mistakes are registering on the wrong hook, skipping the category, and using a weak permission check.

  • Registering outside the right hook. Abilities registered outside wp_abilities_api_init trigger a _doing_it_wrong() notice and the registration fails, as the Make WordPress Core dev note warns. Always use the 2 hooks in the right order.
  • Skipping the category. Every ability needs exactly one registered category, so register the category first and reuse its slug exactly, including dashes and lowercase letters.
  • Using a vague or unnamespaced name. Names must follow the namespace/ability-name pattern, use only lowercase letters, numbers, dashes, and slashes, and stay descriptive, such as my-plugin/create-draft.
  • Leaving out the schemas. WordPress validates inputs and outputs with a validator based on a subset of JSON Schema Version 4, and the dev note says schemas are mandatory when there is a value to pass or return. A missing schema means no validation and no clear contract for callers.
  • Exposing everything through REST. Remember that show_in_rest defaults to false, and only set it to true for abilities you want outside tools to see. Keep admin-only abilities hidden.
  • Using a weak permission callback. A write ability with no real capability check can be run by any authenticated user, so check a capability that matches the risk every time.
  • Guessing the JSON Schema rules. The validator uses a subset of JSON Schema Version 4, so check the JSON Schema Version 4 specification before you use a keyword you have not seen in an official example.

Frequently asked questions

Do I need to know PHP to use the WordPress Abilities API?

Yes, for now. Registering an ability means writing PHP code with a category, schemas, and two callbacks, and running it from PHP uses wp_get_ability() and execute(). A site owner who does not write code can still benefit when a plugin they install registers abilities for them, and can then use those abilities through the REST API or an AI tool.

Can I use the Abilities API on WordPress 6.8 or older?

No. The API is only available in WordPress 6.9 and above, so the registration functions do not exist on older versions. Update WordPress first, or check class_exists('WP_Ability') in your plugin and show an admin notice when it is missing. A plugin that must support older versions should guard its registration code so it only runs when the class exists.

Is the Abilities API the same as the WordPress REST API?

No. The Abilities API is a registry of tasks with names, schemas, and permission checks, while the REST API is one way to reach those tasks over HTTP. An ability can run from PHP without any REST exposure, and it only appears in REST responses when show_in_rest is set to true. The REST endpoints live under the wp-abilities/v1 namespace.

Do abilities work without an AI tool?

Yes. AI agents are only one caller. The same ability can run from your own PHP code, from another plugin, or from an authenticated REST request, with no AI involved at all. The MCP Adapter is a separate package that connects registered abilities to AI tools, but it is optional and not part of WordPress core.

What happens if my permission callback is wrong?

If it is too strict, legitimate users get an ability_invalid_permissions error and the ability never runs. If it is too loose, any authenticated user may run a write or delete ability they should not touch. Match the check to the risk, using a capability such as read for public facts and manage_options or edit_posts for changes, and recheck it after every change to the ability.

Can one ability call another ability?

Yes, in principle, because an execute callback is ordinary PHP code and can fetch another ability with wp_get_ability() and run it with execute(). Keep the chain short and read-only at first, since each call runs its own permission check and schema validation. A failure in the inner ability returns an error to the outer one, so check every result before you use it.

Sources

  1. Abilities API WordPress Developer Resources
  2. Abilities API in WordPress 6.9 Make WordPress Core
  3. Getting started — Abilities API WordPress Developer Resources
  4. REST API endpoints — Abilities API WordPress Developer Resources
  5. WordPress 6.9 “Gene” WordPress.org
  6. From Abilities to AI Agents: Introducing the WordPress MCP Adapter WordPress Developer Resources

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test