> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/web-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/web-api/api/tag-group.md).

# Tag Group

## Endpoints Overview

| Method | Endpoint                      | Description              |
| ------ | ----------------------------- | ------------------------ |
| GET    | `/api/v2/tagGroup/get`        | List all tag groups      |
| POST   | `/api/v2/tagGroup/create`     | Create a new tag group   |
| POST   | `/api/v2/tagGroup/update`     | Update a tag group       |
| POST   | `/api/v2/tagGroup/remove`     | Delete a tag group       |
| POST   | `/api/v2/tagGroup/addTags`    | Add tags to a group      |
| POST   | `/api/v2/tagGroup/removeTags` | Remove tags from a group |

***

## GET /api/v2/tagGroup/get <a href="#list" id="list"></a>

List all tag groups. Returns paginated results.

### Query Parameters

* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Response

```json
{
    "status": "success",
    "data": {
        "data": [
            {
                "id": "TG_001",
                "name": "Design Styles",
                "color": "blue",
                "tags": ["flat", "material", "skeuomorphic"],
                "description": "Visual design styles"
            }
        ],
        "total": 5,
        "offset": 0,
        "limit": 50
    }
}
```

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/get").then(r => r.json());
```

***

## POST /api/v2/tagGroup/create <a href="#create" id="create"></a>

Create a new tag group.

### Request Body

* `name` string (required) — Group name
* `tags` string\[] (required) — Array of tag names to include
* `color` string (optional) — Group color
* `description` string (optional) — Group description

### Response

Returns the newly created tag group object.

```json
{
    "status": "success",
    "data": {
        "id": "NEW_GROUP_ID",
        "name": "Color Palette",
        "color": "",
        "tags": ["warm", "cool", "neutral"],
        "description": "Tags for color palettes"
    }
}
```

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "Color Palette",
        tags: ["warm", "cool", "neutral"],
        description: "Tags for color palettes"
    })
}).then(r => r.json());
```

***

## POST /api/v2/tagGroup/update <a href="#update" id="update"></a>

Update an existing tag group.

### Request Body

* `id` string (required) — The tag group ID to update
* `name` string (required) — Group name
* `tags` string\[] (required) — Full array of tag names (replaces existing)
* `color` string (optional) — Group color
* `description` string (optional) — Group description

### Response

Returns the updated tag group object.

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "TG_001",
        name: "Updated Group Name",
        tags: ["tag1", "tag2", "tag3"],
        color: "green"
    })
}).then(r => r.json());
```

***

## POST /api/v2/tagGroup/remove <a href="#remove" id="remove"></a>

Delete a tag group. This only removes the group — the tags themselves are not deleted.

### Request Body

* `id` string (required) — The tag group ID to delete

### Response

```json
{
    "status": "success",
    "data": true
}
```

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/remove", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: "TG_001" })
}).then(r => r.json());
```

***

## POST /api/v2/tagGroup/addTags <a href="#add-tags" id="add-tags"></a>

Add tags to an existing tag group.

### Request Body

* `groupId` string (required) — The tag group ID
* `tags` string\[] (required) — Tag names to add
* `removeFromSource` boolean (optional) — If `true`, removes the tags from their current groups before adding to this one

### Response

Returns the updated tag group object.

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/addTags", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        groupId: "TG_001",
        tags: ["minimalist", "modern"]
    })
}).then(r => r.json());
```

***

## POST /api/v2/tagGroup/removeTags <a href="#remove-tags" id="remove-tags"></a>

Remove tags from a tag group. The tags themselves are not deleted, only removed from the group.

### Request Body

* `groupId` string (required) — The tag group ID
* `tags` string\[] (required) — Tag names to remove from the group

### Response

Returns the updated tag group object.

### Example

```javascript
await fetch("http://localhost:41595/api/v2/tagGroup/removeTags", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        groupId: "TG_001",
        tags: ["outdated-tag"]
    })
}).then(r => r.json());
```

***

## Tag Group Properties <a href="#properties" id="properties"></a>

Tag groups returned by the API contain the following properties:

| Property      | Type      | Description                 |
| ------------- | --------- | --------------------------- |
| `id`          | string    | Unique tag group ID         |
| `name`        | string    | Group name                  |
| `color`       | string    | Group color                 |
| `tags`        | string\[] | Array of tag names in group |
| `description` | string    | Group description           |