> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Abilities API Overview

> MainWP Dashboard 6.4 registers 102 abilities for site management, updates, backups, Knowledge, and automation through the WordPress Abilities API.

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 6.4 registers 102 abilities into this framework across seven 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. Earlier Dashboard versions expose a smaller catalog.

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

> [card] [Introduction](https://developer.wordpress.org/news/2025/11/introducing-the-wordpress-abilities-api/)
>
> WordPress Developer Blog

> [card] [Handbook](https://make.wordpress.org/ai/handbook/projects/abilities-api/)
>
> Full framework documentation

> [card] [GitHub](https://github.com/WordPress/abilities-api)
>
> 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.

> [card] [MainWP MCP Server](https://docs.mainwp.com/mcp-server/overview.md)
>
> 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
* A WordPress Application Password or another native WordPress REST authentication method

***

## 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.

### MainWP API Keys

MainWP REST API keys authenticate MainWP REST namespaces such as `mainwp/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**:

```bash theme={null}
curl -u "USERNAME:APPLICATION_PASSWORD" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities"
```

For full setup steps, see [Application Passwords](https://docs.mainwp.com/api-reference/rest-api/application-passwords.md).

Dashboard 6.3 also provides inline credential creation under **MainWP > AI > MainWP MCP** and **MainWP > AI > MainWP Control**. See [AI Menu](https://docs.mainwp.com/dashboard/overview/mainwp-ai.md).

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

```http theme={null}
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 |

```bash theme={null}
curl -u "admin:xxxx" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?category=mainwp-sites"
```

### Get Single Ability

```http theme={null}
GET /wp-json/wp-abilities/v1/abilities/{name}
```

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

```bash theme={null}
curl -u "admin:xxxx" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-sites-v1"
```

### List Categories

```http theme={null}
GET /wp-json/wp-abilities/v1/categories
```

MainWP registers these categories:

| Category | Abilities | Description |
| - | - | - |
| `mainwp-sites` | 30 | Site management and monitoring |
| `mainwp-updates` | 14 | Update detection, previewed execution, and site hold removal |
| `mainwp-clients` | 11 | Client management |
| `mainwp-tags` | 7 | Tag/group management |
| `mainwp-batch` | 1 | Batch operation monitoring |
| `mainwp-knowledge` | 7 | Agency, client, and site Knowledge reads and record management |
| `mainwp-backups` | 32 | Built-in backup tasks, snapshots, restores, storage, and settings |

> [card] [Backup Abilities](https://docs.mainwp.com/api-reference/abilities-api/backups.md)
>
> Discover backup status, preview changes, run tasks, and monitor restores.

> [card] [Sites Abilities](https://docs.mainwp.com/api-reference/abilities-api/sites.md)
>
> 30 abilities for site management

> [card] [Updates Abilities](https://docs.mainwp.com/api-reference/abilities-api/updates.md)
>
> 14 abilities for update management

> [card] [Clients Abilities](https://docs.mainwp.com/api-reference/abilities-api/clients.md)
>
> 11 abilities for client management

> [card] [Tags Abilities](https://docs.mainwp.com/api-reference/abilities-api/tags.md)
>
> 7 abilities for tag management

> [card] [Knowledge Abilities](https://docs.mainwp.com/dashboard/overview/mainwp-knowledge.md#knowledge-tools)
>
> 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.

| Add-on | Category | Abilities | Reference |
| - | - | - | - |
| Advanced Uptime Monitor with Abilities support | `mainwp-advanced-uptime-monitor` | 7 | [Advanced Uptime Monitor Abilities](https://docs.mainwp.com/api-reference/abilities-api/advanced-uptime-monitor.md) |
| Article Uploader with Abilities support | `mainwp-article-uploader` | 2 | [Article Uploader Abilities](https://docs.mainwp.com/api-reference/abilities-api/article-uploader.md) |
| Cache Control 5.3 or later | `mainwp-cache-control` | 8 | [Cache Control Abilities](https://docs.mainwp.com/api-reference/abilities-api/cache-control.md) |
| Clone 5.1 or later | `mainwp-clone` | 3 | [Clone Abilities](https://docs.mainwp.com/api-reference/abilities-api/clone.md) |
| Comments 6.1.0 or later | `mainwp-comments` | 5 | [Comments Abilities](https://docs.mainwp.com/api-reference/abilities-api/comments.md) |
| Cost Tracker Assistant with Abilities support | `mainwp-cost-tracker-assistant` | 2 | [Cost Tracker Assistant Abilities](https://docs.mainwp.com/api-reference/abilities-api/cost-tracker-assistant.md) |
| Custom Dashboard 5.2 or later | `mainwp-custom-dashboard` | 4 | [Custom Dashboard Abilities](https://docs.mainwp.com/api-reference/abilities-api/custom-dashboard.md) |
| Dashboard Lock with Abilities support | `mainwp-dashboard-lock` | 2 | [Dashboard Lock Abilities](https://docs.mainwp.com/api-reference/abilities-api/dashboard-lock.md) |
| Database Updater 5.2.0 or later | `mainwp-database-updater` | 3 | [Database Updater Abilities](https://docs.mainwp.com/api-reference/abilities-api/database-updater.md) |
| Domain Monitor with Abilities support | `mainwp-domain-monitor` | 9 | [Domain Monitor Abilities](https://docs.mainwp.com/api-reference/abilities-api/domain-monitor.md) |
| Fathom with Abilities support | `mainwp-fathom` | 13 | [Fathom Abilities](https://docs.mainwp.com/api-reference/abilities-api/fathom.md) |
| Favorites with Abilities support | `mainwp-favorites` | 3 | [Favorites Abilities](https://docs.mainwp.com/api-reference/abilities-api/favorites.md) |
| File Uploader with Abilities support | `mainwp-file-uploader` | 8 | [File Uploader Abilities](https://docs.mainwp.com/api-reference/abilities-api/file-uploader.md) |
| Google Analytics with Abilities support | `mainwp-google-analytics` | 9 | [Google Analytics Abilities](https://docs.mainwp.com/api-reference/abilities-api/google-analytics.md) |
| Google Search Console 6.3 or later | `mainwp-google-search-console` | 10 | [Google Search Console Abilities](https://docs.mainwp.com/api-reference/abilities-api/google-search-console.md) |
| Jetpack Protect with Abilities support | `mainwp-jetpack-protect` | 10 | [Jetpack Protect Abilities](https://docs.mainwp.com/api-reference/abilities-api/jetpack-protect.md) |
| Lighthouse with Abilities support | `mainwp-lighthouse` | 2 | [Lighthouse Abilities](https://docs.mainwp.com/api-reference/abilities-api/lighthouse.md) |
| Maintenance with Abilities support | `mainwp-maintenance` | 2 | [Maintenance Abilities](https://docs.mainwp.com/api-reference/abilities-api/maintenance.md) |
| Matomo 5.2 or later | `mainwp-matomo` | 12 | [Matomo Abilities](https://docs.mainwp.com/api-reference/abilities-api/matomo.md) |
| Patchstack 6.2 or later | `mainwp-patchstack` | 5 | [Patchstack Abilities](https://docs.mainwp.com/api-reference/abilities-api/patchstack.md) |
| Post Plus with Abilities support | `mainwp-post-plus` | 2 | [Post Plus Abilities](https://docs.mainwp.com/api-reference/abilities-api/post-plus.md) |
| SSL Monitor with Abilities support | `mainwp-ssl-monitor` | 3 | [SSL Monitor Abilities](https://docs.mainwp.com/api-reference/abilities-api/ssl-monitor.md) |
| Staging 5.2 or later | `mainwp-staging` | 2 | [Staging Abilities](https://docs.mainwp.com/api-reference/abilities-api/staging.md) |
| Team Control 5.2 or later | See add-on reference | 12 | [Team Control](https://docs.mainwp.com/add-ons/agency/team-control-extension.md) |
| Time Tracker 5.2.0 or later | `mainwp-time-tracker` | 12 | [Time Tracker Abilities](https://docs.mainwp.com/api-reference/abilities-api/time-tracker.md) |
| Virusdie with Abilities support | `mainwp-virusdie` | 4 | [Virusdie Abilities](https://docs.mainwp.com/api-reference/abilities-api/virusdie.md) |
| Termageddon with Abilities support | `mainwp-termageddon` | 10 | [Termageddon Abilities](https://docs.mainwp.com/api-reference/abilities-api/termageddon.md) |
| URL Extractor 5.1 or later | `mainwp-url-extractor` | 10 | [URL Extractor Abilities](https://docs.mainwp.com/api-reference/abilities-api/url-extractor.md) |
| WooCommerce Shortcuts 5.1 or later | `mainwp-woocommerce-shortcuts` | 1 | [WooCommerce Shortcuts Abilities](https://docs.mainwp.com/api-reference/abilities-api/woocommerce-shortcuts.md) |
| White Label with Abilities support | `mainwp-white-label` | 2 | [White Label Abilities](https://docs.mainwp.com/api-reference/abilities-api/white-label.md) |
| WooCommerce Status with Abilities support | `mainwp-woocommerce-status` | 2 | [WooCommerce Status Abilities](https://docs.mainwp.com/api-reference/abilities-api/woocommerce-status.md) |
| Pressable with Abilities support | `mainwp-pressable` | 11 | [Pressable Abilities](https://docs.mainwp.com/api-reference/abilities-api/pressable.md) |
| Pro Reports with Abilities support | `mainwp-pro-reports` | 11 | [Pro Reports Abilities](https://docs.mainwp.com/api-reference/abilities-api/pro-reports.md) |
| WP Rocket with Abilities support | `mainwp-wp-rocket` | 2 | [WP Rocket Abilities](https://docs.mainwp.com/api-reference/abilities-api/wp-rocket.md) |
| Wordfence with Abilities support | `mainwp-wordfence` | 3 | [Wordfence Abilities](https://docs.mainwp.com/api-reference/abilities-api/wordfence.md) |
| WordPress SEO with Abilities support | `mainwp-wordpress-seo` | 2 | [WordPress SEO Abilities](https://docs.mainwp.com/api-reference/abilities-api/wordpress-seo.md) |

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](https://docs.mainwp.com/api-reference/abilities-api/advanced-uptime-monitor.md) for availability and provider limits.

> [!NOTE]
>
> 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](https://docs.mainwp.com/add-ons/backups/updraftplus-extension.md#abilities-api-availability) 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 theme={null}
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](https://developer.wordpress.org/reference/classes/wp_rest_abilities_v1_run_controller/validate_request_method/); 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 for protected changes, including deletion and 6.3 update execution or hold removal |
| `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.

***

## Related Resources

* [MCP Server](https://docs.mainwp.com/mcp-server/overview.md) - Connect AI assistants to MainWP
* [Sites Abilities](https://docs.mainwp.com/api-reference/abilities-api/sites.md) - Site management abilities
* [REST API Overview](https://docs.mainwp.com/api-reference/rest-api/overview.md) - Alternative REST API
* [Batch Operations](https://docs.mainwp.com/api-reference/abilities-api/batch-operations.md) - Monitor batch jobs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.