Skip to main content
MainWP registers 7 tag management abilities into the WordPress Abilities API framework. Tags (also called groups) help organize sites for filtering and batch operations.

​
What You’ll Learn

  • Listing, filtering, and retrieving tag information
  • Creating, updating, and deleting tags
  • Retrieving sites and clients associated with tags

​
mainwp/list-tags-v1

List MainWP tags with pagination and filtering. Method: GET (readonly) 
curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-tags-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
pageintegerNo1Page number
per_pageintegerNo20Items per page (max 100)
searchstringNo""Search term
includearrayNo[]Tag IDs to include
excludearrayNo[]Tag IDs to exclude
Response: 
{
  "items": [
    {
      "id": 1,
      "name": "Production",
      "color": "#3498db",
      "sites_count": 25
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 10
}

​
mainwp/get-tag-v1

Get detailed information about a single tag. Method: POST 
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
tag_idintegerYes—Tag ID
Response: 
{
  "id": 1,
  "name": "Production",
  "color": "#3498db",
  "sites_count": 25,
  "created_at": "2023-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

​
mainwp/add-tag-v1

Create a new tag. Method: POST 
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"name":"Staging","color":"#e74c3c"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/add-tag-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
namestringYes—Tag name
colorstringNo—Hex color code (e.g., #3498db)
Response: 
{
  "id": 5,
  "name": "Staging",
  "color": "#e74c3c",
  "sites_count": 0,
  "created_at": "2024-01-15T10:00:00Z"
}

​
mainwp/update-tag-v1

Update an existing tag. Method: POST 
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1,"name":"Production Sites","color":"#27ae60"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/update-tag-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
tag_idintegerYes—Tag ID
namestringNo—Tag name
colorstringNo—Hex color code
Response: Returns the updated tag object.

​
mainwp/delete-tag-v1

Delete a tag. This is a destructive operation that requires confirmation. Method: POST 
# Dry run to preview
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1,"dry_run":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-tag-v1/run'

# Actual deletion
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1,"confirm":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-tag-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
tag_idintegerYes—Tag ID
confirmbooleanConditional—Required and must be true unless dry_run is true
dry_runbooleanNofalsePreview without deleting
Response: 
{
  "deleted": true,
  "tag_id": 1,
  "tag_name": "Production"
}
Dry run response: 
{
  "dry_run": true,
  "tag_id": 1,
  "tag_name": "Production",
  "sites_affected": 25
}

​
mainwp/get-tag-sites-v1

Get sites associated with a tag. Method: POST 
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-sites-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
tag_idintegerYes—Tag ID
pageintegerNo1Page number
per_pageintegerNo20Items per page
Response: 
{
  "tag_id": 1,
  "tag_name": "Production",
  "sites": [
    {
      "id": 1,
      "url": "https://site1.example.com",
      "name": "Site 1",
      "status": "connected"
    },
    {
      "id": 2,
      "url": "https://site2.example.com",
      "name": "Site 2",
      "status": "connected"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 25
}

​
mainwp/get-tag-clients-v1

Get clients associated with a tag (clients whose sites have this tag). Method: POST 
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"tag_id":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-clients-v1/run'
Input Parameters:
NameTypeRequiredDefaultDescription
tag_idintegerYes—Tag ID
pageintegerNo1Page number
per_pageintegerNo20Items per page
Response: 
{
  "tag_id": 1,
  "tag_name": "Production",
  "clients": [
    {
      "id": 1,
      "name": "Acme Corp",
      "email": "[email protected]",
      "sites_with_tag": 3
    },
    {
      "id": 2,
      "name": "Beta Inc",
      "email": "[email protected]",
      "sites_with_tag": 2
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 5
}