Skip to main content
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)
Use the MainWP Postman collection as the source of truth for request and response schemas.
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
  • How long-running update actions return responses

​
Base URL

All v2 endpoints use: 
https://your-dashboard.com/wp-json/mainwp/v2/
Use Bearer token authentication for v2: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/basic"

​
Set Up API Keys

1

Configure permalinks

Go to WP Admin > Settings > Permalinks and choose any option except Plain.Permalinks settings
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 your integration requires /mainwp/v1, enable MainWP REST API v1 Compatibility to generate legacy Consumer Key and Consumer Secret in the same creation flow.Add API key with v1 compatibility enabled
5

Save and store credentials

Click Save Key, then copy the generated credentials and store them safely.
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.
PermissionMethodsPurpose
ReadGETFetch data
Write & DeletePOST, PUT, PATCH, DELETECreate, update, and remove resources

​
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

Sites

Site inventory, sync, plugins, themes, and site operations.

Clients

Client CRUD, client fields, and client-level site/cost endpoints.

Tags

Tag CRUD, plus related sites and clients.

Updates

Update listing, execution, and ignore management.

Costs

Cost tracker records, linked sites/clients, and batch operations.

Users

User listing, create/edit/delete, CSV import, and admin password updates.

Settings

General, advanced, monitoring, email, tools, and other settings domains.

Monitoring

Uptime monitor list, incidents, heartbeat, and monitor settings.

API Keys

REST API key list, create, edit, and delete endpoints.

Posts

Cross-site post listing and post CRUD actions.

Pages

Cross-site page listing and page CRUD actions.

Batch

Global /batch orchestration across multiple controllers.
For extension-specific endpoints, see Extensions Endpoints.

​
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. The v2 API key endpoints create and manage v2 keys and do not create legacy v1 credentials. 
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.
Build new integrations on v2 first. Use v1 only where an existing integration still requires it.

​
Batch Update Response Handling

Some update endpoints start background work and return a start or queue confirmation immediately instead of waiting for completion. 
{
  "success": 1,
  "message": "Batch updates all started successfully.",
  "last_time_start_batch_updates": "2024-09-03T16:57:29"
}
Depending on your Dashboard version and execution mode, responses can also include fields such as job_id and queued_count. After you receive a start or queued response, wait for the process to finish, then sync your Dashboard or recheck update endpoints.