Abilities API

https://github.com/wordpress/abilities-api
Admin
The Abilities API provides a common way for WordPress core, plugins, and themes to describe their...
Tokens:48,610
Snippets:304
Trust Score:9.1
License:GPL-2.0
Update:5 days ago
Show doc for...
Tokens:
Raw
### Example: Get all registered abilities

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Iterates over all abilities and prints name, label, and description.

```php
// Example: Get all registered abilities
$all_abilities = wp_get_abilities();

foreach ( $all_abilities as $name => $ability ) {
    echo 'Ability Name: ' . esc_html( $ability->get_name() ) . "\n";
    echo 'Label: ' . esc_html( $ability->get_label() ) . "\n";
    echo 'Description: ' . esc_html( $ability->get_description() ) . "\n";
    echo "---\n";
}
```

--------------------------------

### List Abilities - Example Request (curl)

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Sends a GET request to the abilities endpoint. No authentication is shown in this example.

```bash
curl https://example.com/wp-json/wp-abilities/v1/abilities
```

--------------------------------

### GET Request Examples

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Shows curl commands for executing read-only abilities via GET. Includes a no-input example and a URL-encoded input example.

```bash
# No input
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info/run

# With input (URL-encoded)
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"
```

--------------------------------

### Example: Get and execute a specific ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Retrieves 'my-plugin/get-site-info' and executes it, handling WP_Error and success.

```php
// Example:
$site_info_ability = wp_get_ability( 'my-plugin/get-site-info' );

if ( $site_info_ability ) {
	// Ability exists and is registered
	$site_info = $site_info_ability->execute();
	if ( is_wp_error( $site_info ) ) {
		// Handle WP_Error
		echo 'Error: ' . $site_info->get_error_message();
	} else {
		// Use $site_info array
		echo 'Site Name: ' . $site_info['name'];
	}
} else {
	// Ability not found or not registered
}
```

--------------------------------

### POST Request Examples

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Shows curl commands for executing regular abilities via POST. Includes a no-input example and a JSON body input example.

```bash
# No input
curl -X POST https://example.com/wp-json/wp-abilities/v1/my-plugin/create-draft/run

# With input
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run
```

--------------------------------

### List Categories - Example Request (curl with authentication)

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Sends a GET request to the categories endpoint using basic authentication with a username and application password.

```bash
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/categories
```

--------------------------------

### Start the local development environment

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Command to launch the WordPress environment via wp-env.

```bash
npm run wp-env start
```

--------------------------------

### Install development dependencies

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Commands to set the Node.js version, install NPM dependencies, and optionally install Composer dependencies.

```bash
## If you're using nvm, make sure to use the correct Node.js version:
nvm install && nvm use

## Then install the NPM dependencies:
npm install

# If you are using Composer locally, also run:
composer install
```

--------------------------------

### List Abilities - Example Response (JSON)

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example JSON response for the abilities endpoint, showing an ability object with name, label, description, category, output_schema, and meta fields.

```json
[
  {
    "name": "my-plugin/get-site-info",
    "label": "Get Site Information",
    "description": "Retrieves basic information about the WordPress site.",
    "category": "site-information",
    "output_schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Site name"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Site URL"
        }
      }
    },
    "meta": {
      "annotations": {
        "instructions": "",
        "readonly": false,
        "destructive": true,
        "idempotent": false
      }
    }
  }
]
```

--------------------------------

### Success Response Example

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example JSON response for a successful ability execution.

```json
{
  "name": "My WordPress Site",
  "url": "https://example.com"
}
```

--------------------------------

### getAbility() - Get a specific ability by name

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Returns a specific ability by name, or null if not found. The example retrieves the 'my-plugin/create-post' ability and logs its label if it exists.

```javascript
const ability = await getAbility( 'my-plugin/create-post' );
if ( ability ) {
  console.log( `Found ability: ${ ability.label }` );
}
```

--------------------------------

### Retrieve an Ability: curl request

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Sends a GET request to the ability endpoint with namespace and ability slugs. No authentication is shown in this example.

```bash
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info
```

--------------------------------

### Install Abilities API plugin with WP-CLI

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/getting-started.md

Use WP-CLI to install the Abilities API plugin from the latest GitHub release.

```bash
wp plugin install https://github.com/WordPress/abilities-api/releases/latest/download/abilities-api.zip
```

--------------------------------

### Register and execute an ability with wp_register_ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/getting-started.md

Complete example showing how to define a callback, register an ability on wp_abilities_api_init, and execute it later.

```php
<?php

// 1. Define a callback function for your ability.
function my_plugin_get_site_title( array $input = array() ): string {
    return get_bloginfo( 'name' );
}

// 2. Register the ability when the Abilities API is initialized.
// Using `wp_abilities_api_init` ensures the API is fully loaded.
add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

function my_plugin_register_abilities() {
    wp_register_ability( 'my-plugin/get-site-title', array(
        'label'               => __( 'Get Site Title', 'my-plugin' ),
        'description'         => __( 'Retrieves the title of the current WordPress site.', 'my-plugin' ),
        'category'            => 'site-info',
        'input_schema'        => array(
            'type'                 => 'object',
            'properties'           => array(),
            'additionalProperties' => false,
        ),
        'output_schema'       => array(
            'type'        => 'string',
            'description' => 'The site title.',
        ),
        'execute_callback'    => 'my_plugin_get_site_title',
        'permission_callback' => '__return_true', // Everyone can access this
        'meta'                => array(
            'show_in_rest' => true, // Optional: expose via REST API
        ),
    ) );
}

// 3. Later, you can retrieve and execute the ability.
add_action( 'admin_init', 'my_plugin_use_ability' );

function my_plugin_use_ability() {
    $ability = wp_get_ability( 'my-plugin/get-site-title' );
    if ( ! $ability ) {
        // Ability not found.
        return;
    }

    $site_title = $ability->execute();
    if ( is_wp_error( $site_title ) ) {
        // Handle execution error
        error_log( 'Execution error: ' . $site_title->get_error_message() );
        return;
    }

    // `$site_title` now holds the result of `get_bloginfo( 'name' )`.
    echo 'Site Title: ' . esc_html( $site_title );
}
```

--------------------------------

### List Categories - Example Response (JSON)

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example JSON response for the categories endpoint, showing a category object with slug, label, description, meta, and _links fields.

```json
[
  {
    "slug": "data-retrieval",
    "label": "Data Retrieval",
    "description": "Abilities that retrieve and return data from the WordPress site.",
    "meta": {},
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories"
        }
      ],
      "abilities": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/?category=data-retrieval"
        }
      ]
    }
  }
]
```

--------------------------------

### Register abilities with wp_abilities_api_init

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of hooking into wp_abilities_api_init to register a custom ability.

```php
add_action('wp_abilities_api_init', 'my_plugin_register_abilities');
/**
 * Register custom abilities.
 */
function my_plugin_register_abilities() {
    wp_register_ability( 'my-plugin/ability', array(
        'label'               => __( 'Title', 'my-plugin' ),
        'description'         => __( 'Description.', 'my-plugin' ),
        'category'            => 'analytics',
        'input_schema'        => array(
            'type'                 => 'object',
            'properties'           => array(),
            'additionalProperties' => false,
        ),
        'output_schema'       => array(
            'type'        => 'string',
            'description' => 'The site title.',
        ),
        'execute_callback'    => 'my_plugin_get_site_title',
        'permission_callback' => '__return_true', // Everyone can access this
        'meta'                => array(
            'show_in_rest' => true, // Optional: expose via REST API
        ),
    ) );
}
```

--------------------------------

### Example 2: Execute ability with input parameters

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Executes 'my-plugin/update-option' with an input array, handling WP_Error and success.

```php
// Example 2: Ability with input parameters
$ability = wp_get_ability( 'my-plugin/update-option' );
if ( $ability ) {
    $input = array(
        'option_name'  => 'blogname',
        'option_value' => 'My Updated Site Name',
    );

    $result = $ability->execute( $input );
    if ( is_wp_error( $result ) ) {
        // Handle WP_Error
        echo 'Error: ' . $result->get_error_message();
    } else {
        // Use $result
        if ( $result['success'] ) {
            echo 'Option updated successfully!';
            echo 'Previous value: ' . $result['previous_value'];
        }
    }
}
```

--------------------------------

### Usage example: wp_register_ability_args

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of using the wp_register_ability_args filter to modify ability arguments, including label, description, and permission callback.

```php
add_filter( 'wp_register_ability_args', 'my_modify_ability_args', 10, 2 );
/**
 * Modify ability args before validation.
 *
 * @param array<string,mixed> $args         The arguments used to instantiate the ability.
 * @param string              $ability_name The name of the ability, with its namespace.
 *
 * @return array<string,mixed> The modified ability arguments.
 */
function my_modify_ability_args( array $args, string $ability_name ): array {
    // Check if the ability name matches what you're looking for.
    if ( 'my-namespace/my-ability' !== $ability_name ) {
      return $args;
    }

    // Modify the args as needed.
    $args['label'] = __('My Custom Ability Label');

    // You can use the old args to build new ones.
    $args['description'] = sprintf(
        /* translators: 1: Ability name 2: Previous description */
        __('This is a custom description for the ability %s. Previously the description was %s', 'text-domain'),
        $ability_name,
        $args['description'] ?? 'N/A'
    );

    // Even if they're callbacks.
    $args['permission_callback' ] = static function ( $input = null ) use ( $args, $ability_name ) {
        $previous_check = is_callable( $args['permission_callback'] ) ? $args['permission_callback']( $input ) : true;

        // If we already failed, no need for stricter checks.
        if ( ! $previous_check || is_wp_error( $previous_check ) ) {
            return $previous_check;
        }

        return current_user_can( 'my_custom_ability_cap', $ability_name );
    }

    return $args;
}
```

--------------------------------

### Example 1: Execute ability with no input

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Executes 'my-plugin/get-site-info' without input, handling WP_Error and success.

```php
// Example 1: Ability with no input parameters
$ability = wp_get_ability( 'my-plugin/get-site-info' );
if ( $ability ) {
    $site_info = $ability->execute(); // No input required
    if ( is_wp_error( $site_info ) ) {
        // Handle WP_Error
        echo 'Error: ' . $site_info->get_error_message();
    } else {
        // Use $site_info array
        echo 'Site Name: ' . $site_info['name'];
    }
}
```

--------------------------------

### getAbilityCategories() - Get all ability categories

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Returns all registered ability categories. The example logs the count and then iterates over each category to print its label and description.

```javascript
const categories = await getAbilityCategories();
console.log( `Found ${ categories.length } categories` );

categories.forEach( ( category ) => {
  console.log( `${ category.label }: ${ category.description }` );
} );
```

--------------------------------

### getAbilities() - Get all abilities or filter by category

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Returns all registered abilities, optionally filtered by category slug. Automatically handles pagination. The example shows fetching all abilities and then filtering by the 'data-retrieval' category.

```javascript
// Get all abilities
const abilities = await getAbilities();
console.log( `Found ${ abilities.length } abilities` );

// Get abilities in a specific category
const dataAbilities = await getAbilities( { category: 'data-retrieval' } );
console.log( `Found ${ dataAbilities.length } data retrieval abilities` );
```

--------------------------------

### executeAbility() - Execute an ability with input

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Executes an ability with optional input parameters. The HTTP method is automatically determined: 'readonly' abilities use GET, regular abilities use POST. The example shows both a read-only and a regular ability execution.

```javascript
// Execute a read-only ability (GET)
const data = await executeAbility( 'my-plugin/get-data', {
  id: 123,
} );

// Execute a regular ability (POST)
const result = await executeAbility( 'my-plugin/create-item', {
  title: 'New Item',
  content: 'Item content',
} );
```

--------------------------------

### Log ability execution with wp_before_execute_ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of hooking into wp_before_execute_ability to log each ability execution attempt.

```php
add_action( 'wp_before_execute_ability', 'log_ability_execution', 10, 2 );
/**
 * Log each ability execution attempt.
 * @param string $ability_name The name of the ability being executed.
 * @param mixed  $input        The input data passed to the ability.
 */
function log_ability_execution( string $ability_name, $input ) {
    error_log( 'About to execute ability: ' . $ability_name );
    if ( $input !== null ) {
        error_log( 'Input: ' . wp_json_encode( $input ) );
    }
}
```

--------------------------------

### Install Abilities API as a Composer dependency

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/getting-started.md

Use Composer to require the Abilities API package for your project.

```bash
composer require wordpress/abilities-api
```

--------------------------------

### Usage example: wp_register_ability_category_args

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of using the wp_register_ability_category_args filter to modify category label and description for a specific slug.

```php
add_filter( 'wp_register_ability_category_args', 'my_modify_category_args', 10, 2 );
/**
 * Modify category args before validation.
 *
 * @param array<string,mixed> $args The arguments used to instantiate the category.
 * @param string              $slug The slug of the category being registered.
 *
 * @return array<string,mixed> The modified category arguments.
 */
function my_modify_category_args( array $args, string $slug ): array {
    if ( 'my-category' === $slug ) {
        $args['label'] = __( 'My Custom Label', 'my-plugin' );
        $args['description'] = __( 'My custom description for this category.', 'my-plugin' );
    }
    return $args;
}
```

--------------------------------

### Error Response Example

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example JSON error response when an ability lacks necessary permissions, with HTTP status 403.

```json
{
  "code": "ability_invalid_permissions",
  "message": "Ability \"my-plugin/update-option\" does not have necessary permission.",
  "data": {
    "status": 403
  }
}
```

--------------------------------

### Retrieve an Ability: JSON response

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example response for the ability endpoint. Contains name, label, description, category, output_schema, and meta with annotations.

```json
{
  "name": "my-plugin/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "category": "site-information",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {
    "annotations": {
      "instructions": "",
      "readonly": true,
      "destructive": false,
      "idempotent": false
    }
  }
}
```

--------------------------------

### Usage: getAbilities, getAbility, executeAbility

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Shows how to use the client in a WordPress plugin or theme JavaScript. It demonstrates fetching all abilities, getting a specific ability, and executing an ability with parameters.

```javascript
// In your WordPress plugin or theme JavaScript
const { getAbilities, getAbility, executeAbility } = wp.abilities;
// or import { getAbilities, getAbility, executeAbility } from '@wordpress/abilities'; depending on your setup

// Get all abilities
const abilities = await getAbilities();

// Get a specific ability
const ability = await getAbility( 'my-plugin/my-ability' );

// Execute an ability
const result = await executeAbility( 'my-plugin/my-ability', {
  param1: 'value1',
  param2: 'value2',
} );
```

--------------------------------

### Generate PHP code coverage report

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Commands to start the environment with Xdebug coverage enabled and run the PHP tests.

```bash
npm run env start -- --xdebug=coverage

npm run test:php
```

--------------------------------

### Example: Check if an ability is registered

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Checks if 'my-plugin/get-site-info' is registered using wp_has_ability().

```php
$ability_name = 'my-plugin/get-site-info';
if ( wp_has_ability( $ability_name ) ) {
    // Ability is registered
}
```

--------------------------------

### Register categories with wp_abilities_api_categories_init

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of hooking into wp_abilities_api_categories_init to register custom ability categories.

```php
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );
/**
 * Register custom ability categories.
 *
 * @param \WP_Ability_Categories_Registry $registry The category registry instance.
 */
function my_plugin_register_categories( $registry ) {
    wp_register_ability_category( 'ecommerce', array(
        'label' => __( 'E-commerce', 'my-plugin' ),
        'description' => __( 'Abilities related to e-commerce functionality.', 'my-plugin' ),
    ));

    wp_register_ability_category( 'analytics', array(
        'label' => __( 'Analytics', 'my-plugin' ),
        'description' => __( 'Abilities that provide analytical data and insights.', 'my-plugin' ),
    ));
}
```

--------------------------------

### Error Handling Example

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/javascript-client.md

Demonstrates how to catch and handle errors from API functions, showing the specific error codes that may be returned.

```APIDOC
## Error Handling

### Description
All functions return promises that may reject with specific error codes. The example shows how to catch and handle these errors.

### Error Codes
- **ability_permission_denied** - Permission denied.
- **ability_invalid_input** - Invalid input.
- **rest_ability_not_found** - Ability not found.

### Example
```javascript
try {
  const result = await executeAbility( 'my-plugin/restricted-action', input );
  console.log( 'Success:', result );
} catch ( error ) {
  switch ( error.code ) {
    case 'ability_permission_denied':
      console.error( 'Permission denied:', error.message );
      break;
    case 'ability_invalid_input':
      console.error( 'Invalid input:', error.message );
      break;
    case 'rest_ability_not_found':
      console.error( 'Ability not found:', error.message );
      break;
    default:
      console.error( 'Execution failed:', error.message );
  }
}
```
```

--------------------------------

### executeAbility( name, input ) - Execute an ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/javascript-client.md

Executes an ability with optional input data. The example shows executing without input and with input parameters, then iterating over the returned posts.

```javascript
// Execute without input
const siteTitle = await executeAbility( 'my-plugin/get-site-title' );
console.log( 'Site:', siteTitle );

// Execute with input parameters
const posts = await executeAbility( 'my-plugin/get-posts', {
  category: 'news',
  limit: 5,
} );
posts.forEach( ( post ) => console.log( post.title ) );
```

--------------------------------

### Check Abilities API version with WP_ABILITIES_API_VERSION

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/getting-started.md

Use the WP_ABILITIES_API_VERSION constant to ensure a minimum version is installed.

```php
if ( ! defined( 'WP_ABILITIES_API_VERSION' ) || version_compare( WP_ABILITIES_API_VERSION, '0.1.0', '<' ) ) {
  // E.g. add an admin notice about the required version.
  add_action( 'admin_notices', static function() {
    wp_admin_notice(
      esc_html__( 'This plugin requires Abilities API version 0.1.0 or higher. Please update the plugin dependency.', 'my-plugin' ),
      'error'
    );
  } );
  return;
}
```

--------------------------------

### Retrieve a Category: JSON response

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Example response for the category endpoint. Contains slug, label, description, meta, and _links with self, collection, and abilities links.

```json
{
  "slug": "data-retrieval",
  "label": "Data Retrieval",
  "description": "Abilities that retrieve and return data from the WordPress site.",
  "meta": {},
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1/categories"
      }
    ],
    "abilities": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1?category=data-retrieval"
      }
    ]
  }
}
```

--------------------------------

### Example 3: Execute ability with complex input validation

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Executes 'my-plugin/send-email' with an input array, handling WP_Error and success.

```php
// Example 3: Ability with complex input validation
$ability = wp_get_ability( 'my-plugin/send-email' );
if ( $ability ) {
    $input = array(
        'to'      => 'user@example.com',
        'subject' => 'Hello from WordPress',
        'message' => 'This is a test message from the Abilities API.',
    );

    $result = $ability->execute( $input );
    if ( is_wp_error( $result ) ) {
        // Handle WP_Error
        echo 'Error: ' . $result->get_error_message();
    } elseif ( $result['sent'] ) {
        echo 'Email sent successfully!';
    } else {
        echo 'Email failed to send.';
    }
}
```

--------------------------------

### getAbilities() - Discover all registered abilities

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/javascript-client.md

Returns an array of all registered abilities (both server-side and client-side). Accepts an optional args object with a 'category' filter. The example shows listing all abilities and filtering by category.

```javascript
import { getAbilities } from '@wordpress/abilities';

const abilities = await getAbilities();
console.log(`Found ${abilities.length} abilities`);

// List all abilities
abilities.forEach(ability => {
  console.log(`${ability.name}: ${ability.description}`);
});

// Get abilities in a specific category
const dataAbilities = await getAbilities( { category: 'data-retrieval' } );

console.log( `Found ${ dataAbilities.length } data retrieval abilities` );
```

--------------------------------

### registerAbility() - Register a client-side ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Registers a client-side ability that executes locally in the browser. Requires a callback function and a valid category. The example registers an ability that navigates to a URL.

```javascript
import { registerAbility } from '@wordpress/abilities';

await registerAbility( {
  name: 'my-plugin/navigate',
  label: 'Navigate to URL',
  description: 'Navigates to a URL within WordPress admin',
  category: 'navigation',
  input_schema: {
    type: 'object',
    properties: {
      url: { type: 'string' },
    },
    required: [ 'url' ],
  },
  callback: async ( { url } ) => {
    window.location.href = url;
    return { success: true };
  },
} );
```

--------------------------------

### GET /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Retrieves a single ability by its namespace and ability name. This endpoint returns ability details such as label, description, category, and output schema.

```APIDOC
## GET /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)

### Description
Retrieves a single ability by its namespace and ability name.

### Method
GET

### Endpoint
/wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace part of the ability name.
- **ability** (string) - Required - The ability name part.

### Request Example
```bash
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info
```

### Response
#### Success Response (200)
- **name** (string) - The full name of the ability.
- **label** (string) - The human-readable label of the ability.
- **description** (string) - A description of the ability.
- **category** (string) - The category of the ability.
- **output_schema** (object) - The output schema of the ability.
- **meta** (object) - Additional metadata.

#### Response Example
```json
{
  "name": "my-plugin/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "category": "site-information",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {
    "annotations": {
      "instructions": "",
      "readonly": true,
      "destructive": false,
      "idempotent": false
    }
  }
}
```
```

--------------------------------

### React with WordPress Data: useSelect and abilitiesStore

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Shows how to use the data store with @wordpress/data in a React component. It uses useSelect to get all abilities and a specific ability, then renders them in a list.

```javascript
import { useSelect } from '@wordpress/data';
import { store as abilitiesStore } from '@wordpress/abilities';

function MyComponent() {
  const abilities = useSelect(
    ( select ) => select( abilitiesStore ).getAbilities(),
    []
  );

  const specificAbility = useSelect(
    ( select ) => select( abilitiesStore ).getAbility( 'my-plugin/my-ability' ),
    []
  );

  return (
    <div>
      <h2>All Abilities</h2>
      <ul>
        { abilities.map( ( ability ) => (
          <li key={ ability.name }>
            <strong>{ ability.label }</strong>: { ability.description }
          </li>
        ) ) }
      </ul>
    </div>
  );
}
```

--------------------------------

### GET|POST|DELETE /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Executes an ability. The HTTP method depends on the ability's type: GET for read-only, POST for regular with input, DELETE for destructive.

```APIDOC
## GET|POST|DELETE /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run

### Description
Executes an ability. The required HTTP method depends on the ability's functionality and annotations: read-only abilities use GET, regular abilities use GET when readonly and POST when they require input, destructive abilities use DELETE.

### Method
GET, POST, or DELETE

### Endpoint
/wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace part of the ability name.
- **ability** (string) - Required - The ability name part.

#### Query Parameters
- **input** (integer|number|boolean|string|array|object|null) - Optional - Input data for the ability as defined by its input schema. For GET and DELETE requests, pass as `input` query parameter (URL-encoded JSON).

#### Request Body
- **input** (integer|number|boolean|string|array|object|null) - Optional - Input data for the ability. For POST requests, pass in JSON body.

### Request Example
```bash
# GET no input
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info/run

# GET with input (URL-encoded)
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"

# POST no input
curl -X POST https://example.com/wp-json/wp-abilities/v1/my-plugin/create-draft/run

# POST with input
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run

# DELETE with input (URL-encoded)
curl -X DELETE "https://example.com/wp-json/wp-abilities/v1/my-plugin/delete-post/run?input=%7B%22post_id%22%3A123%7D"
```

### Response
#### Success Response (200)
- **name** (string) - Example: "My WordPress Site"
- **url** (string) - Example: "https://example.com"

#### Response Example
```json
{
  "name": "My WordPress Site",
  "url": "https://example.com"
}
```

#### Error Response (403)
- **code** (string) - Error code, e.g., "ability_invalid_permissions"
- **message** (string) - Error message
- **data** (object) - Contains status code

#### Error Response Example
```json
{
  "code": "ability_invalid_permissions",
  "message": "Ability \"my-plugin/update-option\" does not have necessary permission.",
  "data": {
    "status": 403
  }
}
```
```

--------------------------------

### Handle promise rejection with error codes

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/javascript-client.md

Use try/catch with a switch on error.code to handle specific rejection reasons from executeAbility. The example covers permission denied, invalid input, and ability not found errors, with a default case for other failures.

```javascript
try {
  const result = await executeAbility( 'my-plugin/restricted-action', input );
  console.log( 'Success:', result );
} catch ( error ) {
  switch ( error.code ) {
    case 'ability_permission_denied':
      console.error( 'Permission denied:', error.message );
      break;
    case 'ability_invalid_input':
      console.error( 'Invalid input:', error.message );
      break;
    case 'rest_ability_not_found':
      console.error( 'Ability not found:', error.message );
      break;
    default:
      console.error( 'Execution failed:', error.message );
  }
}
```

--------------------------------

### Build the package

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/releasing-a-new-package-version.md

Run the clean and build scripts to generate build files.

```bash
run clean && npm run build
```

--------------------------------

### Clone the repository

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Initial step to download the project source code.

```bash
git clone https://github.com/WordPress/abilities-api.git
```

--------------------------------

### getAbilityCategory() - Get a specific ability category by slug

Source: https://github.com/wordpress/abilities-api/blob/trunk/packages/client/README.md

Returns a specific ability category by slug, or null if not found. The example retrieves the 'data-retrieval' category and logs its label and description if it exists.

```javascript
const category = await getAbilityCategory( 'data-retrieval' );
if ( category ) {
  console.log( `Found category: ${ category.label }` );
  console.log( `Description: ${ category.description }` );
}
```

--------------------------------

### Build the plugin for distribution

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Command to create a zip file of the plugin for distribution.

```bash
npm run plugin-zip
```

--------------------------------

### Ability Registration Parameters

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Detailed documentation of the $args array keys used when registering a WordPress ability.

```APIDOC
## Ability Registration Parameters

### Description
This section documents the parameters accepted by the ability registration function. The $args array accepts the following keys.

### Parameters

#### $args array
- **label** (string) - Required - A human-readable name for the ability. Used for display purposes. Should be translatable.
- **description** (string) - Required - A detailed description of what the ability does, its purpose, and its parameters or return values. This is crucial for AI agents to understand how and when to use the ability. Should be translatable.
- **category** (string) - Required - The slug of the category this ability belongs to. The category must be registered before registering the ability using wp_register_ability_category(). Categories help organize and filter abilities by their purpose.
- **input_schema** (array) - Optional - A JSON Schema definition describing the expected input parameters for the ability's execute callback. Only needed when creating Abilities that require inputs. Defaults to null only when no schema is provided. Used for validation and documentation.
- **output_schema** (array) - Required - A JSON Schema definition describing the expected format of the data returned by the ability. Used for validation and documentation.
- **execute_callback** (callable) - Required - The PHP function or method to execute when this ability is called. The callback receives one optional argument, the input data for the ability. The argument is required when the input schema is defined. The input argument will have the same type as defined in the input schema (e.g., array, object, string, etc.). The callback should return the result of the ability's operation or return a WP_Error object on failure.
- **permission_callback** (callable) - Required - A callback function to check if the current user has permission to execute this ability. The callback receives one optional argument, the input data for the ability. The argument is required when the input schema is defined. The input argument will have the same type as defined in the input schema (e.g., array, object, string, etc.). The callback should return a boolean (true if the user has permission, false otherwise), or a WP_Error object on failure. If an input schema is set, and the input does not validate against the input schema, the permission callback will not be called, and a WP_Error will be returned instead.
- **meta** (array) - Optional - An associative array for storing arbitrary additional metadata about the ability.
  - **annotations** (array) - Optional - An associative array of annotations providing hints about the ability's behavior characteristics. Supports the following keys:
    - **instructions** (string) - Optional - Custom instructions or guidance for using the ability (default: '').
    - **readonly** (boolean) - Optional - Whether the ability only reads data without modifying its environment (default: false).
    - **destructive** (boolean) - Optional - Whether the ability may perform destructive updates to its environment. If true, the ability may perform any type of modification, including deletions or other destructive changes. If false, the ability performs only additive updates (default: true).
    - **idempotent** (boolean) - Optional - Whether calling the ability repeatedly with the same arguments will have no additional effect on its environment (default: false).
  - **show_in_rest** (boolean) - Optional - Whether to expose this ability via the REST API. Default: false. When true, the ability will be listed in REST API responses and can be executed via REST endpoints. When false, the ability will be hidden from REST API listings and cannot be executed via REST endpoints, but remains available for internal PHP usage.
- **ability_class** (string) - Optional - The fully-qualified class name of a custom ability class that extends WP_Ability. This allows you to customize the behavior of an ability by extending the base WP_Ability class and overriding its methods. The custom class must extend WP_Ability. Default: WP_Ability.
```

--------------------------------

### Format project files

Source: https://github.com/wordpress/abilities-api/blob/trunk/CONTRIBUTING.md

Command to format all project files including JavaScript, JSON, and Markdown.

```bash
npm run format
```

--------------------------------

### GET /wp-abilities/v1/categories

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/rest-api.md

Retrieves a paginated list of ability categories. Supports pagination parameters.

```APIDOC
## GET /wp-abilities/v1/categories

### Description
Retrieves a paginated list of ability categories. Supports pagination parameters.

### Method
GET

### Endpoint
/wp-abilities/v1/categories

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Current page of the collection. Default: 1.
- **per_page** (integer) - Optional - Maximum number of items to return per page. Default: 50, Maximum: 100.

### Request Example
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/categories

### Response
#### Success Response (200)
- **slug** (string) - Category slug.
- **label** (string) - Human-readable label.
- **description** (string) - Description of the category.
- **meta** (object) - Metadata.
- **_links** (object) - Hypermedia links.

#### Response Example
[
  {
    "slug": "data-retrieval",
    "label": "Data Retrieval",
    "description": "Abilities that retrieve and return data from the WordPress site.",
    "meta": {},
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories"
        }
      ],
      "abilities": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/?category=data-retrieval"
        }
      ]
    }
  }
]
```

--------------------------------

### Register and execute a client-side ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/javascript-client.md

Registers a new ability with a callback and permission check, then executes it using the ability name.

```javascript
// showNotification function
const showNotification = ( message ) => {
  new Notification( message );
  return { success: true, displayed: message };
};

// Register a notification ability which calls the showNotification function
await registerAbility( {
  name: 'my-plugin/show-notification',
  label: 'Show Notification',
  description: 'Display a notification message to the user',
  input_schema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
      type: { type: 'string', enum: [ 'success', 'error', 'warning', 'info' ] },
    },
    required: [ 'message' ],
  },
  callback: async ( { message, type = 'info' } ) => {
    // Show browser notification
    if ( ! ( 'Notification' in window ) ) {
      alert( 'This browser does not support desktop notification' );
      return {
        success: false,
        error: 'Browser does not support notifications',
      };
    }
    if ( Notification.permission !== 'granted' ) {
      Notification.requestPermission().then( ( permission ) => {
        if ( permission === 'granted' ) {
          return showNotification( message );
        }
      } );
    }
    return showNotification( message );
  },
  permissionCallback: () => {
    return !! wp.data.select( 'core' ).getCurrentUser();
  },
} );

// Use the registered ability
const result = await executeAbility( 'my-plugin/show-notification', {
  message: 'Hello World!',
  type: 'success',
} );
```

--------------------------------

### Register a simple data retrieval Ability without an input schema

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Registers an ability 'my-plugin/get-site-info' that retrieves site information. It defines an output schema and uses an execute_callback that returns site name, description, and URL. The permission_callback is set to '__return_true'.

```php
add_action( 'wp_abilities_api_init', 'my_plugin_register_site_info_ability' );
function my_plugin_register_site_info_ability() {
    wp_register_ability( 'my-plugin/get-site-info', array(
        'label' => __( 'Get Site Information', 'my-plugin' ),
        'description' => __( 'Retrieves basic information about the WordPress site including name, description, and URL.', 'my-plugin' ),
        'category' => 'data-retrieval',
        'output_schema' => array(
            'type' => 'object',
            'properties' => array(
                'name' => array(
                    'type' => 'string',
                    'description' => 'Site name'
                ),
                'description' => array(
                    'type' => 'string',
                    'description' => 'Site tagline'
                ),
                'url' => array(
                    'type' => 'string',
                    'format' => 'uri',
                    'description' => 'Site URL'
                )
            )
        ),
        'execute_callback' => function() {
            return array(
                'name' => get_bloginfo( 'name' ),
                'description' => get_bloginfo( 'description' ),
                'url' => home_url()
            );
        },
        'permission_callback' => '__return_true',
        'meta' => array(
            'annotations' => array(
                'readonly' => true,
                'destructive' => false
            ),
        ),
    ));
}
```

--------------------------------

### Log ability result with wp_after_execute_ability

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/hooks.md

Example of hooking into wp_after_execute_ability to log the result of each ability execution.

```php
add_action( 'wp_after_execute_ability', 'log_ability_result', 10, 3 );
/**
 * Log the result of each ability execution.
 *
 * @param string $ability_name The name of the executed ability.
 * @param mixed  $input        The input data passed to the ability.
 * @param mixed  $result       The result returned by the ability.
 */
function log_ability_result( string $ability_name, $input, $result ) {
    error_log( 'Completed ability: ' . $ability_name );
    error_log( 'Result: ' . wp_json_encode( $result ) );
}
```

--------------------------------

### wp_get_ability_categories()

Source: https://github.com/wordpress/abilities-api/blob/trunk/docs/php-api.md

Gets all registered categories as an associative array keyed by slug. Each value is an instance of WP_Ability_Category.

```APIDOC
## wp_get_ability_categories()

### Description
Get all registered categories as an associative array keyed by slug.

### Function Signature
```php
wp_get_ability_categories() array
```

### Return
- (array) - An associative array of all registered categories, keyed by slug. Each value is an instance of WP_Ability_Category.
```
Tokens:
Raw