Abilities API Overview - MainWP Documentation

The WordPress Abilities API is a WordPress Core feature (available in WordPress 6.9+) that provides a standardized registry for capabilities across the WordPress ecosystem. Any plugin can register discrete actions (“abilities”) with defined input/output schemas, making functionality discoverable by external systems. MainWP Dashboard registers 62 abilities into this framework across five categories. This integration enables AI agents, automation platforms, and external tools to discover what MainWP can do and execute those capabilities through a consistent interface.

What You’ll Learn

How the Abilities API enables discovery of MainWP capabilities
Available ability categories and endpoints
How to execute abilities and handle responses
Error handling for AI agent integrations

Introduction

WordPress Developer Blog

Handbook

Full framework documentation

GitHub

Source and issues

How It Works

The Abilities API adds a discovery layer to WordPress. AI agents and automation tools query /wp-abilities/v1/abilities to see all available actions, their input schemas, output schemas, and behavioral annotations. This enables dynamic discovery of what operations are possible and automated parameter validation.

MainWP MCP Server

Connect Claude, VS Code Copilot, and Cursor to your MainWP Dashboard through the Model Context Protocol. The MCP Server exposes MainWP abilities as tools that AI assistants can call directly.

Prerequisites

WordPress 6.9 or later
MainWP Dashboard 6.0 or later
WordPress user with manage_options capability
API key with appropriate permissions

Base URL

All Abilities API endpoints use the WordPress Abilities namespace:

https://your-dashboard.com/wp-json/wp-abilities/v1/

Authentication

The Abilities API accepts any WordPress REST API authentication method.

Bearer Token

Use the same API keys generated in Dashboard > API Access > API Keys > Add API Keys:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities"

Application Passwords

Create an Application Password in Dashboard > API Access > Application Passwords:

curl -u "USERNAME:APPLICATION_PASSWORD" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities"

For full setup steps, see Application Passwords.

Discovery Endpoints

These endpoints let you explore what abilities are available.

List All Abilities

GET /wp-json/wp-abilities/v1/abilities

Returns registered abilities with pagination.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Items per page (max 100)
`category`	string	—	Filter by category slug

curl -u "admin:xxxx" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?category=mainwp-sites"

Get Single Ability

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

Returns full details for a specific ability including input/output schemas.

curl -u "admin:xxxx" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-sites-v1"

GET /wp-json/wp-abilities/v1/categories

MainWP registers these categories:

Category	Abilities	Description
`mainwp-sites`	30	Site management and monitoring
`mainwp-updates`	13	Update detection and execution
`mainwp-clients`	11	Client management
`mainwp-tags`	7	Tag/group management
`mainwp-batch`	1	Batch operation monitoring

Sites Abilities

30 abilities for site management

Updates Abilities

13 abilities for update management

Clients Abilities

11 abilities for client management

Tags Abilities

7 abilities for tag management

Executing Abilities

Endpoint

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

HTTP Methods

Choose the method from the ability’s meta.annotations:

GET - Read-only abilities (readonly: true), including those that require input.
DELETE - Non-read-only abilities with both destructive: true and idempotent: true.
POST - All other write abilities, including destructive abilities marked idempotent: false.

For example, mainwp/delete-tag-v1 uses DELETE, while mainwp/delete-site-v1 and mainwp/delete-client-v1 use POST. These methods follow WordPress Abilities method validation; using the wrong method returns rest_ability_invalid_method with HTTP 405.

Input Handling

MainWP Dashboard 6.2 supports the following input formats for mainwp/* ability run routes. GET requests: Omit input only when the ability’s schema supplies suitable defaults. To provide filters or required values, send the input object as JSON in the input_json query parameter. Use --data-urlencode with curl -G to encode it correctly:

curl -G -u "admin:xxxx" \
  --data-urlencode 'input_json={"site_id_or_domain":1,"include_stats":true}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-site-v1/run"

input_json preserves JSON types such as booleans, arrays, and null for schema validation. The JSON value must be an object and must not exceed 8 KiB (8,192 bytes). Do not send both input and input_json. Legacy bracket-style query parameters remain supported, but a JSON string in the plain input parameter is not decoded by this adapter. Keep credentials out of query strings. POST requests: Pass an input object in the JSON body:

curl -X POST -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"site_ids_or_domains":[1]}}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/sync-sites-v1/run"

DELETE requests: Use an application/json body containing only an input object. This keeps operation inputs out of the URL. For example, preview a tag deletion:

curl -X DELETE -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"tag_id":1,"dry_run":true}}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-tag-v1/run"

After reviewing the preview, execute with confirm: true and dry_run: false. The DELETE body must not exceed 1 MiB (1,048,576 bytes). Do not combine a body with input or input_json query parameters. Existing bracket-style input query parameters remain supported when no body is sent, but the JSON body is preferred. input_json is a GET-only parameter. Malformed JSON, conflicting input sources, unsupported DELETE body formats, and input exceeding the transport limits return mainwp_abilities_invalid_input_transport with HTTP 400. Valid transport still has to pass the individual ability’s input schema and permission checks.

Response Format

Success

Abilities return their defined output schema directly:

{
  "items": [
    {
      "id": 1,
      "url": "https://example.com",
      "name": "My Site",
      "status": "connected"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 150
}

Errors

Error responses follow WordPress REST API conventions:

{
  "code": "ability_invalid_input",
  "message": "Invalid parameter: site_id_or_domain is required",
  "data": {
    "status": 400
  }
}

Ability Annotations

Each ability includes metadata describing its behavior:

Annotation	Type	Description
`readonly`	boolean	True if ability only reads data
`destructive`	boolean	True if ability deletes data
`idempotent`	boolean	True if repeated calls have no additional effect
`instructions`	string	Custom usage guidance

These annotations help AI agents make informed decisions about which abilities to call and in what order.

Error Reference

Abilities API Errors

Code	HTTP	Description
`ability_invalid_input`	400	Input fails JSON Schema validation
`ability_missing_input_schema`	400	Required input not provided
`ability_invalid_permissions`	403	Permission callback returned false
`ability_invalid_output`	500	Output fails validation
`rest_ability_not_found`	404	Ability not registered
`rest_ability_invalid_method`	405	Wrong HTTP method for ability type

MainWP-Specific Errors

Code	HTTP	Description
`mainwp_abilities_invalid_input_transport`	400	Invalid JSON input format, conflicting input sources, or transport size limit exceeded
`mainwp_site_not_found`	404	Site ID or domain not found
`mainwp_client_not_found`	404	Client ID or email not found
`mainwp_tag_not_found`	404	Tag ID not found
`mainwp_job_not_found`	404	Batch job expired or not found
`mainwp_confirmation_required`	400	Destructive operation missing `confirm: true`
`mainwp_site_offline`	503	Site unreachable
`mainwp_module_not_available`	501	Required module not active

Feature-Gated Abilities

Some abilities require optional MainWP modules:

Module	Required For
Cost Tracker	`get-site-costs-v1`, `get-client-costs-v1`
Logs	`get-site-changes-v1`

If the required module is inactive, these abilities return a mainwp_module_not_available error.

MCP Server - Connect AI assistants to MainWP
Sites Abilities - Site management abilities
REST API Overview - Alternative REST API
Batch Operations - Monitor batch jobs

​What You’ll Learn

Introduction

Handbook

GitHub

​How It Works

MainWP MCP Server

​Prerequisites

​Base URL

​Authentication

​Bearer Token

​Application Passwords

​Discovery Endpoints

​List All Abilities

​Get Single Ability

​List Categories

Sites Abilities

Updates Abilities

Clients Abilities

Tags Abilities

​Executing Abilities

​Endpoint

​HTTP Methods

​Input Handling

​Response Format

​Success

​Errors

​Ability Annotations

​Error Reference

​Abilities API Errors

​MainWP-Specific Errors

​Feature-Gated Abilities

​Related Resources