Batch Endpoint

Reference for the global MainWP REST API v2 /batch endpoint and how it differs from controller-specific batch endpoints.

Use /batch when you need one request to fan out into multiple controller actions.

Use the MainWP Postman collection as the source of truth for request and response schemas.

Global Batch Route

Method	Path	Purpose	Key Params
POST, PUT, PATCH	/batch	Execute grouped batch operations across multiple controllers	Controller payload objects (sites, clients, tags)

Global Batch Behavior

The global /batch controller is orchestration-focused:

• Supports grouped create requests for sites, clients, and tags
• Supports additional site action arrays under sites such as sync, reconnect, disconnect, suspend, check, remove, security, plugins, themes, non-mainwp-changes
• Enforces a request item limit (mainwp_rest_batch_items_limit, default 100)

Each group must be an object containing supported action arrays. Use objects for create items and positive site IDs for the additional site actions. A malformed group or unsupported action returns a group-level rest_invalid_param error, and that group is not executed.

The global endpoint rejects updates, costs, and unknown groups with rest_batch_group_not_supported. Use Updates Endpoints for updates and /costs/batch for cost operations. Inspect the returned groups and per-item errors even when the overall request returns HTTP 200; valid groups can still run alongside a rejected group.

---

Global Batch Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sites": {
      "create": [
        {"url":"https://site-a.com","name":"Site A","admin":"admin","uniqueid":"xxxxx"}
      ],
      "sync": [12, 19]
    },
    "tags": {
      "create": [
        {"name":"Managed"}
      ]
    }
  }' \
  "https://your-dashboard.com/wp-json/mainwp/v2/batch"

{
  "sites": {
    "create": [{"success": 1}],
    "sync": [{"success": 1}]
  },
  "tags": {
    "create": [{"success": 1}]
  }
}

Site create requests must include the connection credential required by the child site’s MainWP Child settings: adminpassword, uniqueid, or both.

---

Global vs Controller-Specific Batch

Use controller-specific batch endpoints when you need dedicated CRUD batching for that controller:

• /sites/batch
• /clients/batch
• /tags/batch
• /costs/batch

Use global /batch when you need a single orchestrated request spanning multiple controller types.

---

Related Resources

• Sites Endpoints
• Clients Endpoints
• Tags Endpoints
• Costs Endpoints