Skip to content

5.rest-api.md

Latest commit

 

History

History
200 lines (153 loc) · 4.84 KB

5.rest-api.md

File metadata and controls

200 lines (153 loc) · 4.84 KB

5. REST API Reference

The WordPress Abilities API provides REST endpoints that allow external systems to discover and execute abilities via HTTP requests.

User access

Access to all Abilities REST API endpoints requires an authenticated user (see the Authentication section). Access to execute individual Abilities is restricted based on the permission_callback() of the Ability.

Schema

The Abilities API endpoints are available under the /wp/v2/abilities namespace.

Ability Object

Abilities are represented in JSON with the following structure:

{
  "name": "my-plugin/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {}
}

List Abilities

Definition

GET /wp/v2/abilities

Arguments

  • page (integer): Current page of the collection. Default: 1.
  • per_page (integer): Maximum number of items to return per page. Default: 50, Maximum: 100.

Example Request

curl https://example.com/wp-json/wp/v2/abilities

Example Response

[
  {
    "name": "my-plugin/get-site-info",
    "label": "Get Site Information",
    "description": "Retrieves basic information about the WordPress site.",
    "output_schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Site name"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Site URL"
        }
      }
    },
    "meta": {}
  }
]

Retrieve an Ability

Definition

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

Arguments

  • namespace (string): The namespace part of the ability name.
  • ability (string): The ability name part.

Example Request

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

Example Response

{
  "name": "my-plugin/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {}
}

Execute an Ability

Definition

POST /wp/v2/abilities/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run

Arguments

  • namespace (string): The namespace part of the ability name.
  • ability (string): The ability name part.
  • input (integer|number|boolean|string|array|object|null): Optional input data for the ability as defined by its input schema.

Example Request (No Input)

curl -X POST https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info/run

Example Request (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/v2/abilities/my-plugin/update-option/run

Example Response (Success)

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

Example Response (Error)

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

Authentication

The Abilities API supports all WordPress REST API authentication methods:

  • Cookie authentication (same-origin requests)
  • Application passwords (recommended for external access)
  • Custom authentication plugins

Using Application Passwords

curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp/v2/abilities

Error Responses

The API returns standard WordPress REST API error responses with these common codes:

  • ability_missing_input_schema – the ability requires input but none was provided.
  • ability_invalid_input - input validation failed according to the ability's schema.
  • ability_invalid_permissions - current user lacks permission to execute the ability.
  • ability_invalid_output - output validation failed according to the ability's schema.
  • ability_invalid_execute_callback - the ability's execute callback is not callable.
  • rest_ability_not_found - the requested ability is not registered.
  • rest_ability_invalid_method - the requested HTTP method is not allowed for executing the selected ability.
  • rest_ability_cannot_execute - the ability cannot be executed due to insufficient permissions.