MainWP

https://docs.mainwp.com/
Admin
MainWP is an open-source, self-hosted WordPress management solution that enables users to manage,...
Tokens:392,728
Snippets:4,069
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Get Site Plugins Response

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

Example response for the get-site-plugins-v1 endpoint. Shows the structure with site details, plugin list, and total count.

```json
{
  "site_id": 1,
  "site_url": "https://site1.example.com",
  "plugins": [
    {
      "slug": "akismet/akismet.php",
      "name": "Akismet Anti-spam",
      "version": "5.3",
      "active": true,
      "update_version": "5.3.1"
    }
  ],
  "total": 15
}
```

--------------------------------

### Install and Login to MainWP Control

Source: https://docs.mainwp.com/api-reference/mainwp-control

Installs the mainwpcontrol command globally and performs the initial login and ability listing. Requires a MainWP Dashboard and credentials.

```bash
npm install -g @mainwp/control
mainwpcontrol login
mainwpcontrol abilities list

```

--------------------------------

### Start Legacy Backups (backups.php)

Source: https://docs.mainwp.com/customization/disable-wp-cron

Starts legacy backups. Schedule every hour. Configure only when the built-in MainWP Legacy Backup feature is enabled.

```bash
/usr/bin/php /path/to/public_html/wp-content/plugins/mainwp/cron/backups.php > /dev/null 2>&1
```

--------------------------------

### Get Sites Basic (GET)

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

GET request to retrieve minimal site information (ID, URL, name) for all sites. The response includes a list of sites and a total count.

```bash
curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-sites-basic-v1/run'

```

```json
{
  "sites": [
    {
      "id": 1,
      "url": "https://site1.example.com",
      "name": "Site 1"
    },
    {
      "id": 2,
      "url": "https://site2.example.com",
      "name": "Site 2"
    }
  ],
  "total": 150
}

```

--------------------------------

### GET /wp-json/wp-abilities/v1/abilities/mainwp/get-site-themes-v1/run

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

Gets list of themes installed on a child site.

```APIDOC
## GET /wp-json/wp-abilities/v1/abilities/mainwp/get-site-themes-v1/run

### Description
Gets list of themes installed on a child site.

### Method
GET (readonly)

### Endpoint
`/wp-json/wp-abilities/v1/abilities/mainwp/get-site-themes-v1/run`

### Parameters
#### Query Parameters
- `input_json` (string) - Required - JSON string containing:
  - `site_id_or_domain` (integer|string) - Required - Site ID or domain

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

### Response
#### Success Response (200)
- `site_id` (integer) - The site ID
- `site_url` (string) - The site URL
- `active_theme` (string) - The active theme slug
- `themes` (array) - List of themes, each with:
  - `slug` (string) - Theme slug
  - `name` (string) - Theme name
  - `version` (string) - Theme version
  - `active` (boolean) - Whether the theme is active
  - `update_version` (string|null) - Available update version or null
- `total` (integer) - Total number of themes

#### Response Example
```json
{
  "site_id": 1,
  "site_url": "https://site1.example.com",
  "active_theme": "twentytwentyfour",
  "themes": [
    {
      "slug": "twentytwentyfour",
      "name": "Twenty Twenty-Four",
      "version": "1.0",
      "active": true,
      "update_version": null
    }
  ],
  "total": 3
}
```
```

--------------------------------

### Get Refresh Policy Example Response

Source: https://docs.mainwp.com/api-reference/abilities-api/google-search-console

Example response from Get Refresh Policy. `scheduler_mode` is `wordpress`, `external`, or `disabled`; `schedule_state` is `scheduled`, `unscheduled`, or `drifted`. `last_refresh_at` and `next_refresh_at` can be `null`.

```json
{
  "report_period": "month",
  "auto_refresh": true,
  "refresh_hours": 9,
  "scheduler_mode": "wordpress",
  "schedule_state": "scheduled",
  "last_refresh_at": "2026-09-23T06:00:00Z",
  "next_refresh_at": "2026-09-23T15:00:00Z",
  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

```

--------------------------------

### MainWP MCP settings.json example

Source: https://docs.mainwp.com/mcp-server/reference/configuration

Example settings.json file for the MainWP MCP server. Place it in ./settings.json or ~/.config/mainwp-mcp/settings.json. As of @mainwp/mcp 1.2.0, security settings like requireUserConfirmation: false, skipSslVerify: true, and allowHttp: true are ignored in the working-directory file.

```json
{
  "dashboardUrl": "https://your-dashboard.com",
  "username": "admin",
  "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
  "skipSslVerify": false,
  "safeMode": false,
  "schemaVerbosity": "standard",
  "rateLimit": 60
}
```

--------------------------------

### Get Single Ability

Source: https://docs.mainwp.com/api-reference/abilities-api/overview

Get full details for a specific ability, including input/output schemas. The curl example retrieves the 'mainwp/list-sites-v1' ability.

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

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

--------------------------------

### Add client with mainwp/add-client-v1

Source: https://docs.mainwp.com/api-reference/abilities-api/clients

Creates a new client using the mainwp/add-client-v1 endpoint. The `name` parameter is required; other fields like `client_email`, `client_phone`, and `selected_sites` are optional. The response returns the created client object in the same format as `get-client-v1`.

```bash
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"name":"New Client","client_email":"client@example.com","client_phone":"+1-555-0100"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run'

```

--------------------------------

### Get site themes with mainwp/get-site-themes-v1

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

Gets the list of themes installed on a child site using the mainwp/get-site-themes-v1 ability. This is a readonly GET request that requires site_id_or_domain. The response includes the site ID, site URL, active theme, an array of theme details, and the total count.

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

```json
{
  "site_id": 1,
  "site_url": "https://site1.example.com",
  "active_theme": "twentytwentyfour",
  "themes": [
    {
      "slug": "twentytwentyfour",
      "name": "Twenty Twenty-Four",
      "version": "1.0",
      "active": true,
      "update_version": null
    }
  ],
  "total": 3
}
```

--------------------------------

### GET mainwp/get-site-plugins-v1

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

Retrieves the list of plugins installed on a child site, with optional filters for status and update availability.

```APIDOC
## GET mainwp/get-site-plugins-v1

### Description
Retrieves the list of plugins installed on a child site, with optional filters for status and update availability.

### Method
GET

### Endpoint
`https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-site-plugins-v1/run`

### Parameters
#### Query Parameters
- **input_json** (string) - Required - JSON-encoded object containing the following parameters:
  - `site_id_or_domain` (integer|string) - Required - Site ID or domain.
  - `status` (string) - Optional - Filter: `all`, `active`, `inactive`. Default: `all`.
  - `has_update` (boolean) - Optional - Filter to plugins with updates.

### Request Example
```
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"site_id_or_domain":1,"status":"active"}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-site-plugins-v1/run'
```

### Response
#### Success Response (200)
- **site_id** (integer) - The ID of the site.
- **site_url** (string) - The URL of the site.
- **plugins** (array) - List of plugins, each containing:
  - `slug` (string) - Plugin slug.
  - `name` (string) - Plugin name.
  - `version` (string) - Current version.
  - `active` (boolean) - Whether the plugin is active.
  - `update_version` (string) - Available update version, if any.
- **total** (integer) - Total number of plugins.

#### Response Example
```
{
  "site_id": 1,
  "site_url": "https://site1.example.com",
  "plugins": [
    {
      "slug": "akismet/akismet.php",
      "name": "Akismet Anti-spam",
      "version": "5.3",
      "active": true,
      "update_version": "5.3.1"
    }
  ],
  "total": 15
}
```
```

--------------------------------

### Response for mainwp/update-all-v1

Source: https://docs.mainwp.com/api-reference/abilities-api/updates

Example response from the update-all-v1 endpoint. Shows counts of updated core, plugins, themes, and translations, plus a summary with total updated, errors, and sites updated.

```json
{
  "updated": {
    "core": 2,
    "plugins": 15,
    "themes": 3,
    "translations": 5
  },
  "errors": [],
  "summary": {
    "total_updated": 25,
    "total_errors": 0,
    "sites_updated": 10
  }
}
```

--------------------------------

### Batch update start response

Source: https://docs.mainwp.com/api-reference/rest-api/overview

Example JSON response from a batch update endpoint that starts background work and returns a start confirmation immediately. Depending on the Dashboard version and execution mode, responses may include fields such as job_id and queued_count. Wait for the process to finish before syncing or rechecking update endpoints.

```json
{
  "success": 1,
  "message": "Batch updates all started successfully.",
  "last_time_start_batch_updates": "2024-09-03T16:57:29"
}

```

--------------------------------

### POST /wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run

Source: https://docs.mainwp.com/api-reference/abilities-api/clients

Create a new client with the provided details.

```APIDOC
## POST /wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run

### Description
Create a new client.

### Method
POST

### Endpoint
`/wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run`

### Parameters
#### Request Body
- **name** (string) - Required - Client name.
- **client_email** (string) - Optional - Email address.
- **client_phone** (string) - Optional - Phone number.
- **address_1** (string) - Optional - Address line 1.
- **address_2** (string) - Optional - Address line 2.
- **city** (string) - Optional - City.
- **state** (string) - Optional - State/Province.
- **zip** (string) - Optional - ZIP/Postal code.
- **country** (string) - Optional - Country.
- **note** (string) - Optional - Notes.
- **selected_sites** (array) - Optional - Site IDs to associate.

### Request Example
```
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"name":"New Client","client_email":"client@example.com","client_phone":"+1-555-0100"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run'
```

### Response
#### Success Response (200)
Returns the created client object (same format as `get-client-v1`).
```

--------------------------------

### Install MainWP MCP plugin

Source: https://docs.mainwp.com/mcp-server/claude-code-plugin

Install the MainWP MCP plugin for Claude Code, which sets up the MCP server, the mainwp-dashboard agent skill, and ten /mainwp:* workflow commands in one step.

```shell
/plugin marketplace add mainwp/mainwp-mcp
/plugin install mainwp@mainwp-mcp

```

--------------------------------

### GET /monitors/{id_or_domain}/incidents

Source: https://docs.mainwp.com/api-reference/rest-api/monitoring

Retrieves a list of incidents for a specific monitor. Supports pagination. Includes a representative request and response example.

```APIDOC
## GET /monitors/{id_or_domain}/incidents

### Description
Get incident list.

### Method
GET

### Endpoint
`/monitors/{id_or_domain}/incidents`

### Parameters
#### Path Parameters
- **id_or_domain** (string) - Required - Numeric site ID or site domain.

#### Query Parameters
- **page** (integer) - Optional - Page number.
- **per_page** (integer) - Optional - Number of items per page.

### Request Example
```
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/monitors/12/incidents?page=1&per_page=20"
```

### Response
#### Success Response (200)
- **success** (integer) - Indicates success (1).
- **total** (integer) - Total number of incidents.
- **data** (array) - List of incidents.
  - **status** (string) - Incident status.
  - **started_at** (string) - Incident start time.

#### Response Example
```
{
  "success": 1,
  "total": 3,
  "data": [
    {
      "status": "down",
      "started_at": "2026-02-01 11:03:00"
    }
  ]
}
```
```

--------------------------------

### Continue Legacy Backups (backups_continue.php)

Source: https://docs.mainwp.com/customization/disable-wp-cron

Continues legacy backups. Schedule every 5 minutes. Configure only when the built-in MainWP Legacy Backup feature is enabled.

```bash
/usr/bin/php /path/to/public_html/wp-content/plugins/mainwp/cron/backups_continue.php > /dev/null 2>&1
```

--------------------------------

### Scan a child site via REST API - Example Request and Response

Source: https://docs.mainwp.com/add-ons/security/mainwp-virusdie-extension

Send a GET request to `/wp-json/mainwp/v1/virusdie/scan` with the `site_id` parameter to request a scan. The example response shows the error returned for a free account. Check for the `error` key before treating the response as successful.

```http
https://example.com/wp-json/mainwp/v1/virusdie/scan?site_id=25&consumer_key=ck_b587cfa39976a2ad47b8fafde84beb70f5d&consumer_secret=cs_75f7a905fa7ae1243570425ede6be026f4731f9c
```

```json
{
  "error": "On-demand scanning requires a paid Virusdie plan."
}

```

--------------------------------

### POST /time-tracker/tasks/{task_id}/start

Source: https://docs.mainwp.com/api-reference/rest-api/extensions

Starts a Time Tracker task.

```APIDOC
## POST /time-tracker/tasks/{task_id}/start

### Description
Starts a Time Tracker task.

### Method
POST

### Endpoint
`/wp-json/mainwp/v2/time-tracker/tasks/{task_id}/start`

### Parameters
#### Path Parameters
- **task_id** (integer) - Required - The ID of the task.

### Request Example
```
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/time-tracker/tasks/44/start"
```
```

--------------------------------

### Get Site Mapping Response (Unmapped)

Source: https://docs.mainwp.com/api-reference/abilities-api/google-search-console

Example response for an unmapped site. The status field is unmapped, mapped, or stale; cache_status is none, fresh, stale, or malformed.

```json
{
  "site_id": 1,
  "status": "unmapped",
  "property_ref": null,
  "connection_ref": null,
  "property_type": null,
  "property_label": null,
  "cache_status": "none",
  "cache_generated_at": null,
  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

```

--------------------------------

### List sites response JSON (mainwp/list-sites-v1)

Source: https://docs.mainwp.com/api-reference/abilities-api/sites

Example response from the list-sites-v1 ability, showing the structure of the returned with items array and pagination fields.

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

--------------------------------

### GET run ability with input_json

Source: https://docs.mainwp.com/api-reference/abilities-api/overview

GET request example using input_json query parameter to pass input as JSON, preserving types. Use --data-urlencode with curl -G to encode correctly. The JSON value must be an object and must not exceed 8 KiB (8,192 bytes). Do not send both input and input_json.

```bash
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"
```

--------------------------------

### Create a user across selected sites

Source: https://docs.mainwp.com/api-reference/rest-api/users

Creates a user on selected sites. The request includes username, email, role, send_password, and websites filter. The response indicates success.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username":"editor01",
    "email":"editor01@example.com",
    "role":"editor",
    "send_password":true,
    "websites":"12,19"
  }' \
  "https://your-dashboard.com/wp-json/mainwp/v2/users/create"
```

```json
{
  "success": 1,
  "message": "Users created successfully."
}
```

--------------------------------

### Multiple dashboards MCP server configuration

Source: https://docs.mainwp.com/mcp-server/reference/configuration

Example AI client configuration for multiple dashboards. Each dashboard gets its own folder with its own settings.json, and the MCP server entry points to that folder with cwd. Because ./settings.json is checked first, each server instance picks up the credentials from its own working directory.

```json
{
  "mcpServers": {
    "mainwp-staging": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "cwd": "/path/to/staging-credentials"
    }
  }
}
```

--------------------------------

### Get monitor incidents for one site

Source: https://docs.mainwp.com/api-reference/rest-api/monitoring

Fetches incident data for a specific monitor site. The request uses the `id_or_domain` parameter, accepting either a numeric site ID or domain. The response provides success status, total count, and incident details including status and start time.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/monitors/12/incidents?page=1&per_page=20"

```

```json
{
  "success": 1,
  "total": 3,
  "data": [
    {
      "status": "down",
      "started_at": "2026-02-01 11:03:00"
    }
  ]
}

```

--------------------------------

### Immediate Response (≤200 sites)

Source: https://docs.mainwp.com/api-reference/abilities-api/batch-operations

Example response for operations on 200 or fewer sites. The operation executes synchronously and returns results immediately, with queued set to false.

```json
{
  "queued": false,
  "synced": [
    {"id": 1, "url": "https://example.com", "name": "Site 1"}
  ],
  "errors": [],
  "total_synced": 1,
  "total_errors": 0
}
```

--------------------------------

### GET /wp-json/wp-abilities/v1/abilities/mainwp/get-site-updates-v1/run

Source: https://docs.mainwp.com/api-reference/abilities-api/updates

Gets available updates for a single site.

```APIDOC
## GET /wp-json/wp-abilities/v1/abilities/mainwp/get-site-updates-v1/run

### Description
Gets available updates for a single site.

### Method
GET (readonly)

### Endpoint
`/wp-json/wp-abilities/v1/abilities/mainwp/get-site-updates-v1/run`

### Parameters
#### Query Parameters
- `input_json` (string) - Required - JSON-encoded input object.
  - `site_id_or_domain` (integer|string) - Required - Site ID or domain.
  - `types` (array) - Optional - Filter: `core`, `plugins`, `themes`, `translations`.

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

### Response
#### Success Response (200)
- `site_id` (integer) - Site ID.
- `site_url` (string) - Site URL.
- `site_name` (string) - Site name.
- `updates` (array) - List of available updates.
  - `type` (string) - Update type (e.g., plugin).
  - `slug` (string) - Item slug.
  - `name` (string) - Item name.
  - `current_version` (string) - Current version.
  - `new_version` (string) - New version.
- `summary` (object) - Summary of updates.
  - `core` (integer) - Number of core updates.
  - `plugins` (integer) - Number of plugin updates.
  - `themes` (integer) - Number of theme updates.
  - `translations` (integer) - Number of translation updates.
  - `total` (integer) - Total number of updates.

#### Response Example
```json
{
  "site_id": 1,
  "site_url": "https://site1.example.com",
  "site_name": "Site 1",
  "updates": [
    {
      "type": "plugin",
      "slug": "akismet/akismet.php",
      "name": "Akismet",
      "current_version": "5.3",
      "new_version": "5.3.1"
    }
  ],
  "summary": {
    "core": 0,
    "plugins": 3,
    "themes": 1,
    "translations": 2,
    "total": 6
  }
}
```
```

--------------------------------

### Run Lighthouse for all sites

Source: https://docs.mainwp.com/api-reference/rest-api/extensions

Initiates a Lighthouse audit across all sites.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/lighthouse/audit"
```
Tokens:
Raw