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

# REST API Overview

> MainWP REST API v2 overview, authentication setup, key lifecycle guidance, and endpoint categories for sites, clients, tags, updates, costs, users, settings, monitoring, API keys, posts, pages, and batch operations.

The MainWP REST API lets you manage your MainWP Dashboard programmatically over HTTP.

The API follows REST conventions, returns JSON responses, and is designed for HTTPS requests.

Authentication options:

* Bearer token (recommended for `/mainwp/v2`)
* Consumer Key and Consumer Secret (legacy `/mainwp/v1`)

> [!NOTE]
>
> Use the [MainWP Postman collection](https://www.postman.com/mainwp/mainwp/collection/ujfddk4/mainwp-rest-api-v2-current) as the source of truth for request and response schemas.

> [!WARNING]
>
> Your MainWP Dashboard URL must be reachable from the system sending API requests. A local-only Dashboard is typically not reachable by external API clients.

## What You'll Learn

* How to authenticate with REST API keys
* How to create v2 API keys and optionally enable v1 compatibility in the UI
* How to manage key permissions and API access state
* Which endpoint category to use for each task
* Where to get the machine-readable OpenAPI specification
* How long-running update actions return responses

***

## Base URL

All v2 endpoints use:

```text theme={null}
https://your-dashboard.com/wp-json/mainwp/v2/
```

Use Bearer token authentication for v2:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/basic"
```

***

## Set Up API Keys

[MainWP REST API - Video Tutorial](https://www.youtube.com/embed/soSpRy8ovBo)

**1. Configure permalinks**

Go to **WP Admin > Settings > Permalinks** and choose any option except **Plain**.

![Permalinks settings](https://mintcdn.com/mainwp/e07i-JbTNXjDT9ia/images/add-ons/c87f79edc47e.jpg?fit=max\&auto=format\&n=e07i-JbTNXjDT9ia\&q=85\&s=2834c18fe8be085c4ba3ac70ab301bbe)

**2. Create a key in API Access**

Go to **MainWP Dashboard > API Access > API Keys > Add API Keys** and enter a key name.

**3. Assign permission scope**

Choose one or more permissions based on the endpoints you plan to call.

* `Read` for `GET`
* `Write & Delete` for `POST`, `PUT`, `PATCH`, and `DELETE`

**4. Optional: enable v1 compatibility**

If an integration requires `/mainwp/v1`, an unrestricted Dashboard administrator can enable **MainWP REST API v1 Compatibility**. This generates a legacy Consumer Key and Consumer Secret alongside the v2 key.

> [!NOTE]
>
> Only unrestricted Dashboard administrators can enable v1 compatibility. Team Control users can still create v2 keys when their role allows it.

![Add API key with v1 compatibility enabled](https://mintcdn.com/mainwp/ZIVj2Ty_YecTFjto/images/api-reference/rest-api-add-key-v1-compatibility.png?fit=max\&auto=format\&n=ZIVj2Ty_YecTFjto\&q=85\&s=bbe7544b526ea51d09180f6b74684372)

**5. Save and store credentials**

Copy the generated credentials while they are visible and store them securely. Then click **Save API Key**.

> [!WARNING]
>
> The API key (Bearer token) is shown once and cannot be revealed later. If you enable v1 compatibility, the Consumer Key and Consumer Secret are also shown once.

**6. Use the token in requests**

Send it in the `Authorization: Bearer ...` header for all v2 calls.

### Permission Scope

This table reflects v2 permission behavior.

| Permission | Methods | Purpose |
| - | - | - |
| Read | GET | Fetch data |
| Write & Delete | POST, PUT, PATCH, DELETE | Create, update, and remove resources |

> [!NOTE]
>
> REST v2 requests on per-user installations can access only sites and tags owned by the key's WordPress user, including administrators. Per-user mode means `mainwp_is_single_user` is set to `false`; default single-user installations are unchanged. Team Control permissions can limit access further, but cannot grant access to another user's records.
>
> Lists omit other users' records. Direct requests for those records return the same error code, HTTP status, and response format as a missing record on that route. Bulk and all-sites operations select only owned sites that the user can access.

***

## Manage API Access State

MainWP REST API stays active while at least one API key is enabled.

* To disable API access, disable all enabled keys in **MainWP Dashboard > API Access > API Keys**.
* To delete keys, use **Delete** for single keys or bulk delete on the same page.

***

## Endpoint Categories

> [card] [Sites](https://docs.mainwp.com/api-reference/rest-api/sites.md)
>
> Site inventory, sync, plugins, themes, and site operations.

> [card] [Clients](https://docs.mainwp.com/api-reference/rest-api/clients.md)
>
> Client CRUD, client fields, and client-level site/cost endpoints.

> [card] [Tags](https://docs.mainwp.com/api-reference/rest-api/tags.md)
>
> Tag CRUD, plus related sites and clients.

> [card] [Updates](https://docs.mainwp.com/api-reference/rest-api/updates.md)
>
> Update listing, execution, and ignore management.

> [card] [Costs](https://docs.mainwp.com/api-reference/rest-api/costs.md)
>
> Cost tracker records, linked sites/clients, and batch operations.

> [card] [Users](https://docs.mainwp.com/api-reference/rest-api/users.md)
>
> User listing, create/edit/delete, CSV import, and admin password updates.

> [card] [Settings](https://docs.mainwp.com/api-reference/rest-api/settings.md)
>
> General, advanced, monitoring, email, tools, and other settings domains.

> [card] [Monitoring](https://docs.mainwp.com/api-reference/rest-api/monitoring.md)
>
> Uptime monitor list, incidents, heartbeat, and monitor settings.

> [card] [API Keys](https://docs.mainwp.com/api-reference/rest-api/api-keys.md)
>
> REST API key list, create, edit, and delete endpoints.

> [card] [Posts](https://docs.mainwp.com/api-reference/rest-api/posts.md)
>
> Cross-site post listing and post CRUD actions.

> [card] [Pages](https://docs.mainwp.com/api-reference/rest-api/pages.md)
>
> Cross-site page listing and page CRUD actions.

> [card] [Batch](https://docs.mainwp.com/api-reference/rest-api/batch.md)
>
> Global `/batch` orchestration across multiple controllers.

For add-on-specific endpoints, see [Add-on Endpoints](https://docs.mainwp.com/api-reference/rest-api/extensions.md).

***

## OpenAPI Specification

A machine-readable OpenAPI 3.1.0 description of the full v2 API is maintained in the documentation repository:

```text theme={null}
https://raw.githubusercontent.com/mainwp/docs/main/api-reference/openapi.yaml
```

Use this URL to import the API into Postman, generate client code, or feed your own tooling. It covers every v2 endpoint, including add-on routes, which are marked with `x-requires-extension` since they respond only when the matching add-on is installed on your Dashboard. The `info.version` field records the MainWP Dashboard version the specification was written against.

***

## Legacy v1 Compatibility

MainWP still supports legacy v1 endpoints (`/wp-json/mainwp/v1/`) for backward compatibility.

In the UI flow (**MainWP Dashboard > API Access > API Keys > Add API Keys**), you can enable **MainWP REST API v1 Compatibility** to generate legacy Consumer Key and Consumer Secret along with the v2 Bearer token.

Only unrestricted Dashboard administrators can create, migrate, or edit v1-compatible keys, even when a Team Control role grants API key permissions. Legacy keys apply across the whole Dashboard. The v2 API key endpoints manage v2 keys.

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

Legacy v1 requests can also pass credentials using an `X-Api-Key` header payload that includes `consumer_key` and `consumer_secret`.

> [!NOTE]
>
> Build new integrations on v2 first. Use v1 only where an existing integration still requires it.

***

## Batch Update Response Handling

Batch update endpoints can queue work, return completed results, or report an existing run.

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

Check the response before deciding what to do next:

* If MainWP reports a new background run, wait for it to finish, then sync your Dashboard or recheck the update endpoints. A queued response can include `job_id` and `queued_count`.
* If MainWP reports completion and includes a `summary`, read the result there.
* If MainWP reports that a batch is already running, check that run before sending another start request.

In MainWP Dashboard 6.4.2 and later, when the Abilities API is unavailable, a batch start can return `failed_site_ids` for sites it could not queue. Other sites in that response can continue processing. If every queue attempt fails, the endpoint returns HTTP 500 with code `mainwp_rest_updates_queue_error`. Check the result before retrying.

***

## Related Resources

* [API Keys Endpoints](https://docs.mainwp.com/api-reference/rest-api/api-keys.md)
* [Application Passwords](https://docs.mainwp.com/api-reference/rest-api/application-passwords.md)
* [MainWP API Introduction](https://docs.mainwp.com/api-reference/introduction.md)
* [OpenAPI Specification (openapi.yaml)](https://raw.githubusercontent.com/mainwp/docs/main/api-reference/openapi.yaml)


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