> 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/zh-tw/api/tag-group.md).

# Tag Group

## 端點概覽

| 方法   | 端點                            | 說明       |
| ---- | ----------------------------- | -------- |
| GET  | `/api/v2/tagGroup/get`        | 列出所有標籤群組 |
| POST | `/api/v2/tagGroup/create`     | 建立新標籤群組  |
| POST | `/api/v2/tagGroup/update`     | 更新標籤群組   |
| POST | `/api/v2/tagGroup/remove`     | 刪除標籤群組   |
| POST | `/api/v2/tagGroup/addTags`    | 將標籤加入群組  |
| POST | `/api/v2/tagGroup/removeTags` | 從群組移除標籤  |

***

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

列出所有標籤群組。回傳分頁結果。

### 查詢參數

* `offset` integer（可選）— 分頁偏移量，預設 `0`
* `limit` integer（可選）— 分頁限制，預設 `50`，最大 `1000`

### 回應

```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
    }
}
```

### 範例

```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>

建立新的標籤群組。

### 請求主體

* `name` string（必填）— 群組名稱
* `tags` string\[]（必填）— 要包含的標籤名稱陣列
* `color` string（可選）— 群組顏色
* `description` string（可選）— 群組說明

### 回應

回傳新建立的標籤群組物件。

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

### 範例

```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>

更新現有的標籤群組。

### 請求主體

* `id` string（必填）— 要更新的標籤群組 ID
* `name` string（必填）— 群組名稱
* `tags` string\[]（必填）— 完整的標籤名稱陣列（會取代現有的）
* `color` string（可選）— 群組顏色
* `description` string（可選）— 群組說明

### 回應

回傳更新後的標籤群組物件。

### 範例

```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>

刪除標籤群組。這只會移除群組本身 — 標籤不會被刪除。

### 請求主體

* `id` string（必填）— 要刪除的標籤群組 ID

### 回應

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

### 範例

```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>

將標籤加入現有的標籤群組。

### 請求主體

* `groupId` string（必填）— 標籤群組 ID
* `tags` string\[]（必填）— 要加入的標籤名稱
* `removeFromSource` boolean（可選）— 若為 `true`，會在加入此群組前先從標籤原本所在的群組中移除

### 回應

回傳更新後的標籤群組物件。

### 範例

```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>

從標籤群組中移除標籤。標籤本身不會被刪除，只是從群組中移除。

### 請求主體

* `groupId` string（必填）— 標籤群組 ID
* `tags` string\[]（必填）— 要從群組中移除的標籤名稱

### 回應

回傳更新後的標籤群組物件。

### 範例

```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 屬性 <a href="#properties" id="properties"></a>

API 回傳的標籤群組包含以下屬性：

| 屬性            | 類型        | 說明         |
| ------------- | --------- | ---------- |
| `id`          | string    | 唯一標籤群組 ID  |
| `name`        | string    | 群組名稱       |
| `color`       | string    | 群組顏色       |
| `tags`        | string\[] | 群組中的標籤名稱陣列 |
| `description` | string    | 群組說明       |