Skip to main content
The MainWP REST API enables external applications to interact with your Dashboard through standard HTTP requests. All endpoints return JSON-formatted responses and require authentication via Bearer token. The API provides approximately 72 endpoints across 6 categories for comprehensive Dashboard management.

​
What You’ll Learn

  • How to authenticate with the REST API
  • Available endpoint categories
  • Request and response formats
  • Pagination and batch operations
  • Error handling

Postman Collection

Interactive API documentation

Authentication Guide

Set up API keys

Dashboard Setup

Enable REST API

​
How It Works

The REST API exposes your MainWP Dashboard functionality through standard HTTP endpoints. External tools send authenticated requests to perform actions like listing sites, triggering updates, or managing clients. Responses return structured JSON data that can be parsed by any programming language or automation platform.

​
Prerequisites

RequirementDetails
MainWP DashboardVersion 5.2 or later
PermalinksPretty permalinks enabled (not “Plain”)
API KeyGenerated in Dashboard > REST API
Network AccessDashboard must be publicly accessible
Your MainWP Dashboard must be accessible via the internet. Locally hosted Dashboards cannot receive external API requests.

​
Base URL

All API requests target your Dashboard’s WordPress REST API namespace: 
https://your-dashboard.com/wp-json/mainwp/v2/
Replace your-dashboard.com with your actual Dashboard domain.

​
Authentication

All API requests require a Bearer token in the Authorization header.

​
Bearer Token

Generate API keys in your Dashboard under Dashboard > REST API > Add API Keys: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/"

​
Permissions

Each API key can have granular permissions:
PermissionMethodsDescription
ReadGETRetrieve data only
WritePOST, PUTCreate or modify data
DeleteDELETERemove data
For detailed setup instructions, see the Authentication Guide.

​
API Categories

Sites

17 endpoints for site management

Clients

4 endpoints for client management

Costs

4 endpoints for cost tracking

Tags

1 endpoint for tag retrieval

Updates

13 endpoints for update management

Extensions

33 endpoints for SSL Monitor & Pro Reports

​
Request Format

The API accepts parameters in different ways depending on the HTTP method:
  • GET requests: Pass parameters as URL query strings
  • POST/PUT requests: Send parameters as JSON in the request body
  • DELETE requests: Usually require only the resource identifier in the URL
Include the Content-Type: application/json header when sending JSON bodies: 
curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Site", "url": "https://example.com"}' \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/add"

​
Response Format

​
Success

All responses return JSON with the requested data: 
{
  "id": 1,
  "url": "https://example.com",
  "name": "My Site",
  "status": "connected"
}

​
Errors

Error responses include a code and message: 
{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": {
    "status": 403
  }
}

​
Pagination

List endpoints support pagination through query parameters:
ParameterTypeDefaultDescription
pageinteger1Current page number
per_pageinteger10Items per page
Response headers include pagination metadata:
HeaderDescription
X-WP-TotalTotal number of items
X-WP-TotalPagesTotal number of pages
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/?page=2&per_page=25"

​
Batch Operations

When triggering batch updates, the API responds immediately with confirmation rather than waiting for completion: 
{
  "success": 1,
  "message": "Batch updates all started successfully.",
  "last_time_start_batch_updates": "2024-09-03T16:57:29"
}
Sync your Dashboard after allowing time for batch operations to complete to see updated results.

​
Error Reference

​
HTTP Status Codes

CodeDescription
200Request succeeded
201Resource created
400Bad request - invalid parameters
401Authentication required or invalid
403Permission denied
404Resource or endpoint not found
405Method not allowed
5XXServer error

​
MainWP-Specific Errors

CodeHTTPDescription
mainwp_site_not_found404Site ID or domain not found
mainwp_client_not_found404Client ID or email not found
mainwp_site_offline503Site unreachable
mainwp_invalid_parameters400Required parameter missing or invalid
rest_forbidden403API key lacks required permission

​
Feature-Gated Endpoints

Some endpoints require optional MainWP extensions:
ExtensionRequired For
Cost Tracker/costs endpoints
SSL Monitor/ssl-monitor endpoints
Pro Reports/pro-reports endpoints
If the required extension is inactive, these endpoints return a 404 or feature-specific error.