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_optionscapability - A WordPress Application Password or another native WordPress REST authentication method
Base URL
All Abilities API endpoints use the WordPress Abilities namespace:Authentication
The Abilities API accepts any WordPress REST API authentication method.MainWP API Keys
MainWP REST API keys authenticate MainWP REST namespaces such asmainwp/v2. They do not authenticate WordPress Abilities routes under wp-abilities/v1, even when the ability name starts with mainwp/. Use an Application Password for the examples on these pages.
Application Passwords
Create an Application Password in Dashboard > API Access > Application Passwords:Site Access and Operation Permissions
Authentication does not override the user’s site access or Team Control permissions. Dashboard 6.3 checks the requested sites and the operation’s required rights. For example, plugin updates need Update Plugins, site deletion needs Delete Sites, client changes need Manage Clients, and tag changes need Manage Groups. Multi-type update calls need the rights for each selected update type. Background jobs recheck their owner’s permissions and site access when they execute. A queued job is not a guarantee that its originally selected sites or actions will still be permitted. Add-on abilities can require their own extension and operation permissions; see each Add-on’s reference.Discovery Endpoints
These endpoints let you explore what abilities are available.List All Abilities
Get Single Ability
List Categories
Backup Abilities
Discover backup status, preview changes, run tasks, and monitor restores.
Sites Abilities
30 abilities for site management
Updates Abilities
14 abilities for update management
Clients Abilities
11 abilities for client management
Tags Abilities
7 abilities for tag management
Knowledge Abilities
7 abilities for saved context, Skills, and Memory
Add-on Abilities
MainWP Add-ons can register additional abilities alongside the 102 Dashboard abilities in version 6.4. These appear only when the relevant Add-on is active.
These Add-ons use the
mainwp/ namespace. Article Uploader provides read-only lists and lookups of staged articles with masked excerpts. Cache Control provides cache status reads, policy changes, Cloudflare credential validation, and single-site cache purging. Clone provides stored policy status, global enablement, and per-site participation settings. Comments provides live and last-sync comment reads, status-checked moderation, and previewed permanent deletion of trashed comments. Cost Tracker Assistant provides read-only Assistant status and a list of costs inside the renewal alert window. Custom Dashboard provides snippet metadata, PHP validation, and previewed snippet replacements and removals. Favorites provides read-only lists of saved favorite plugins, themes, and groups. Dashboard Lock provides read-only status and configuration reads of its stored redirect, IP restriction, and HTTP Basic Authentication settings. Database Updater provides stored database update observations, dispatch previews, and confirmed WooCommerce, Elementor, and Elementor Pro database update dispatches. Domain Monitor provides stored domain expiry summaries and profiles, monitoring policy changes, manual domain profile replacement, single-site domain checks, and scheduled check and expiry-alert requests. File Uploader provides staged-file reads and deletion, previewed deployments to Child sites, deployment status, and rollback. Fathom provides account connection and catalog refresh, site mappings, global settings, live reports, cached analytics refreshes, current visitors, and previewed account removal. Google Search Console provides connection and property reads, site mappings, cached performance summaries, refresh settings, and background refresh jobs. Maintenance provides read-only access to stored cleanup schedules and their accessible target and failed sites. Lighthouse provides a read-only overview and paginated stored desktop and mobile scores for accessible sites. Jetpack Protect provides stored summaries, scans, findings and history, live control state, queued refreshes, and previewed connection and visibility changes. Matomo provides connection management, previewed site assignments, cached analytics and trends, and scheduled refreshes with status and cancellation. SSL Monitor provides read-only stored certificate status and effective monitoring settings for authorized HTTPS sites. Staging provides read-only access to stored staging clones and effective saved settings. Patchstack provides read-only cached connection status, account totals, site protection state, and vulnerability summaries. Post Plus provides read-only lists and lookups of saved post and page drafts with masked excerpts. Time Tracker provides task and bucket management, timer start and pause, and task completion with a billing snapshot. URL Extractor provides extraction templates, background extraction runs across authorized sites, stored records, and one-use TXT and CSV exports. WooCommerce Shortcuts provides a read-only cached WooCommerce status check for an authorized site. WooCommerce Status provides read-only lists and single-store reads of stored sales, order, and stock figures. WordPress SEO provides read-only access to saved Yoast SEO settings templates and their recorded site applications. WP Rocket provides read-only site lists and saved feature settings stored on the Dashboard. Find their references in the Add-on Abilities navigation group.
Advanced Uptime Monitor provides cached monitors and events, live uptime summaries, and monitor creation, state changes, deletion, and inventory synchronization. These abilities require the upcoming Abilities-enabled release; they are absent from the initial 5.4 package. Check the uptime reference for availability and provider limits.
UpdraftPlus 5.2 includes database and runtime groundwork for future backup abilities, but those abilities are disabled by default until compatible MainWP Child support is available. Activating the add-on does not make them available through the Abilities API or MainWP MCP. Use the UpdraftPlus Dashboard workflows in this release.Updating MainWP Child for 6.3 does not enable these backup abilities: its UpdraftPlus protocol still advertises no executable provider operations.
Executing Abilities
Endpoint
HTTP Methods
Choose the method from the ability’smeta.annotations:
- GET - Read-only abilities (
readonly: true), including those that require input. - DELETE - Non-read-only abilities with both
destructive: trueandidempotent: true. - POST - All other write abilities, including destructive abilities marked
idempotent: false.
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 formainwp/* 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:
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:
application/json body containing only an input object. This keeps operation inputs out of the URL. For example, preview a tag deletion:
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:Errors
Error responses follow WordPress REST API conventions:Ability Annotations
Each ability includes metadata describing its behavior:
These annotations help AI agents make informed decisions about which abilities to call and in what order.
Error Reference
Abilities API Errors
MainWP-Specific Errors
Feature-Gated Abilities
Some abilities require optional MainWP modules:
If the required module is inactive, these abilities return a
mainwp_module_not_available error.
Related Resources
- MCP Server - Connect AI assistants to MainWP
- Sites Abilities - Site management abilities
- REST API Overview - Alternative REST API
- Batch Operations - Monitor batch jobs
