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 for the MainWP REST API:

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

Application Passwords

Create an Application Password in WordPress under Users > Profile:

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

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 /wp-json/wp-abilities/v1/abilities/{name}/run

HTTP Methods

Each ability specifies whether it reads or modifies data:

GET — Read-only abilities (marked readonly: true)
POST — Abilities that create, update, or delete data

Input Handling

GET requests: Omit the input parameter to use schema defaults. URL-encoded JSON in query strings does not work reliably.

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

POST requests: Pass input in the JSON body:

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

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_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

Getting Started

Understanding MainWP

Dashboard

Sites

Clients

Troubleshooting

Customization

Advanced

API Reference

Resources

​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