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

# Tags Abilities

> 7 abilities for managing MainWP tags (groups) used to organize child sites.

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)

```bash theme={null}
curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-tags-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `page` | integer | No | 1 | Page number |
| `per_page` | integer | No | 20 | Items per page (max 100) |
| `search` | string | No | "" | Search term |
| `include` | array | No | \[] | Tag IDs to include |
| `exclude` | array | No | \[] | Tag IDs to exclude |

**Response:**

```json theme={null}
{
  "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:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"tag_id":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `tag_id` | integer | Yes | — | Tag ID |

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | Yes | — | Tag name |
| `color` | string | No | — | Hex color code (e.g., `#3498db`) |

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `tag_id` | integer | Yes | — | Tag ID |
| `name` | string | No | — | Tag name |
| `color` | string | No | — | 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:** DELETE

```bash theme={null}
# Dry run to preview
curl -X DELETE -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 DELETE -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:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `tag_id` | integer | Yes | — | Tag ID |
| `confirm` | boolean | Conditional | — | Required and must be `true` unless `dry_run` is `true` |
| `dry_run` | boolean | No | false | Preview without deleting |

**Response:**

```json theme={null}
{
  "deleted": true,
  "tag_id": 1,
  "tag_name": "Production"
}
```

**Dry run response:**

```json theme={null}
{
  "dry_run": true,
  "tag_id": 1,
  "tag_name": "Production",
  "sites_affected": 25
}
```

***

## mainwp/get-tag-sites-v1

Get sites associated with a tag.

**Method:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"tag_id":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-sites-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `tag_id` | integer | Yes | — | Tag ID |
| `page` | integer | No | 1 | Page number |
| `per_page` | integer | No | 20 | Items per page |

**Response:**

```json theme={null}
{
  "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:** GET (readonly)

```bash theme={null}
curl -G -u 'admin:xxxx' \
  --data-urlencode 'input_json={"tag_id":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-tag-clients-v1/run'
```

**Input Parameters:**

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `tag_id` | integer | Yes | — | Tag ID |
| `page` | integer | No | 1 | Page number |
| `per_page` | integer | No | 20 | Items per page |

**Response:**

```json theme={null}
{
  "tag_id": 1,
  "tag_name": "Production",
  "clients": [
    {
      "id": 1,
      "name": "Acme Corp",
      "email": "contact@acme.com",
      "sites_with_tag": 3
    },
    {
      "id": 2,
      "name": "Beta Inc",
      "email": "info@beta.com",
      "sites_with_tag": 2
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 5
}
```

***

## Related Resources

* [Abilities API Overview](/api-reference/abilities-api/overview) - API basics and authentication
* [Sites Abilities](/api-reference/abilities-api/sites) - Site management abilities
* [REST API Tags](/api-reference/rest-api/tags) - REST API alternative for tags


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