Abilities API

These routes let you retrieve registered abilities and their categories, and run an individual ability with input data.

Available routes (endpoints are described below):

/wp-abilities/v1/abilities
/wp-abilities/v1/abilities/{name}
/wp-abilities/v1/abilities/{name}/run
/wp-abilities/v1/categories
/wp-abilities/v1/categories/{slug}

Controller classes:

Contents:

Resource schema

The schema lists fields returned by the resource. Fields depend on the context and user capabilities.

Field Context Description
name view, edit Resource field.
label view, edit Resource field.
description view, edit Resource field.
category view, edit Resource field.
input_schema view, edit Resource field.
output_schema view, edit Resource field.
annotations view, edit Resource field.

/wp-abilities/v1/abilities

An OPTIONS request returns methods, parameters, and the complete schema for the selected route.

$ curl -X OPTIONS -i https://example.com/wp-json/wp-abilities/v1/abilities

Get the list of abilities

Returns registered abilities that are exposed through the REST API. Results can be filtered by category, namespace, and annotations.

Request type

GET /wp-abilities/v1/abilities

Request parameters

$context(string)
Response context: view, embed, or edit.
$page(integer)
Collection page number.
$per_page(integer)
Number of items per page.
$category(string)
Ability category identifier.
$namespace(string)
Ability namespace.
$meta[annotations][readonly](boolean)
Limits results to abilities that do not modify data.
$meta[annotations][destructive](boolean)
Limits results to abilities that may perform destructive changes.
$meta[annotations][idempotent](boolean)
Limits results to abilities for which repeated calls with the same input have no additional effect.

Request example

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

/wp-abilities/v1/abilities/{name}

Get one ability

Returns the specified ability's description: its name, input and output schemas, category, and annotations.

Request type

GET /wp-abilities/v1/abilities/{name}

Request parameters

$name(string) (required)
Unique ability name.
$context(string)
Response context: view, embed, or edit.

Request example

$ curl https://example.com/wp-json/wp-abilities/v1/abilities/{name}

/wp-abilities/v1/abilities/{name}/run

Run an ability

Runs the specified ability. The method depends on its annotations: GET for a read-only ability, DELETE for an idempotent destructive operation, and POST in every other case. The ability's input schema defines the contents of input.

Request type

GET|POST|DELETE /wp-abilities/v1/abilities/{name}/run

Request parameters

$name(string) (required)
Unique ability name.
$input(object|array|string|number|boolean|null)
Ability input. Pass it in the JSON request body for POST, or as a query-string parameter for GET and DELETE.

Replace {name} in the example with a registered ability name, and the contents of input with data that matches its input_schema.

Request example

$ curl -X POST https://example.com/wp-json/wp-abilities/v1/abilities/{name}/run \
  -H 'Content-Type: application/json' \
  -d '{"input":{"include":"version"}}'

/wp-abilities/v1/categories

Get ability categories

Returns the list of registered ability categories.

Request type

GET /wp-abilities/v1/categories

Request parameters

$context(string)
Response context: view, embed, or edit.
$page(integer)
Collection page number.
$per_page(integer)
Number of items per page.

Request example

$ curl https://example.com/wp-json/wp-abilities/v1/categories

/wp-abilities/v1/categories/{slug}

Get one ability category

Returns a category's label, description, and metadata by its identifier.

Request type

GET /wp-abilities/v1/categories/{slug}

Request parameters

$slug(string) (required)
Unique category identifier.
$context(string)
Response context: view, embed, or edit.

Request example

$ curl https://example.com/wp-json/wp-abilities/v1/categories/{slug}