# Tag

## 端點概覽

| 方法   | 端點                           | 說明         |
| ---- | ---------------------------- | ---------- |
| GET  | `/api/v2/tag/get`            | 列出所有標籤     |
| POST | `/api/v2/tag/get`            | 列出標籤（請求主體） |
| GET  | `/api/v2/tag/getRecentTags`  | 取得最近使用的標籤  |
| GET  | `/api/v2/tag/getStarredTags` | 取得已加星號的標籤  |
| POST | `/api/v2/tag/update`         | 重新命名標籤     |
| POST | `/api/v2/tag/merge`          | 合併兩個標籤     |

***

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

列出資源庫中的所有標籤。回傳分頁結果。

### 查詢參數

* `name` string（可選）— 以名稱篩選標籤（子字串匹配）
* `offset` integer（可選）— 分頁偏移量，預設 `0`
* `limit` integer（可選）— 分頁限制，預設 `50`，最大 `1000`

### 回應

```json
{
    "status": "success",
    "data": {
        "data": [
            {
                "name": "design",
                "count": 150,
                "color": "",
                "groups": ["GROUP_ID_1"],
                "pinyin": "design"
            },
            {
                "name": "photography",
                "count": 89,
                "color": "",
                "groups": [],
                "pinyin": "photography"
            }
        ],
        "total": 340,
        "offset": 0,
        "limit": 50
    }
}
```

### 範例

```javascript
// 列出所有標籤（前 50 個）
await fetch("http://localhost:41595/api/v2/tag/get").then(r => r.json());

// 以名稱篩選標籤
await fetch("http://localhost:41595/api/v2/tag/get?name=design").then(r => r.json());

// 分頁瀏覽標籤
await fetch("http://localhost:41595/api/v2/tag/get?offset=50&limit=100").then(r => r.json());
```

***

## POST /api/v2/tag/get <a href="#list-post" id="list-post"></a>

與 GET 相同，但接受 JSON 主體中的篩選參數。

### 請求主體

* `name` string（可選）— 以名稱篩選標籤（子字串匹配）
* `offset` integer（可選）— 分頁偏移量，預設 `0`
* `limit` integer（可選）— 分頁限制，預設 `50`，最大 `1000`

### 範例

```javascript
await fetch("http://localhost:41595/api/v2/tag/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "design", limit: 100 })
}).then(r => r.json());
```

***

## GET /api/v2/tag/getRecentTags <a href="#recent" id="recent"></a>

取得最近使用的標籤。回傳分頁結果。

### 查詢參數

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

### 回應

```json
{
    "status": "success",
    "data": {
        "data": [
            {
                "name": "ui-design",
                "count": 45,
                "color": "",
                "groups": [],
                "pinyin": "ui-design"
            }
        ],
        "total": 12,
        "offset": 0,
        "limit": 50
    }
}
```

### 範例

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

***

## GET /api/v2/tag/getStarredTags <a href="#starred" id="starred"></a>

取得已加星號（釘選）的標籤。回傳分頁結果。

### 查詢參數

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

### 回應

與 `/api/v2/tag/getRecentTags` 格式相同。

### 範例

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

***

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

重新命名現有標籤。所有使用此標籤的項目都會自動更新。

### 請求主體

* `originalName` string（必填）— 目前的標籤名稱
* `name` string（必填）— 新的標籤名稱

### 回應

回傳更新後的標籤物件。

```json
{
    "status": "success",
    "data": {
        "name": "new-tag-name",
        "count": 45,
        "color": "",
        "groups": [],
        "pinyin": "new-tag-name"
    }
}
```

### 範例

```javascript
await fetch("http://localhost:41595/api/v2/tag/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        originalName: "old-tag-name",
        name: "new-tag-name"
    })
}).then(r => r.json());
```

***

## POST /api/v2/tag/merge <a href="#merge" id="merge"></a>

將來源標籤合併到目標標籤。所有擁有來源標籤的項目會被替換為目標標籤。合併後來源標籤會被移除。

### 請求主體

* `source` string（必填）— 要合併的來源標籤名稱（將被移除）
* `target` string（必填）— 要合併至的目標標籤名稱（將被保留）

### 回應

```json
{
    "status": "success",
    "data": {
        "affectedItems": 25,
        "sourceRemoved": true
    }
}
```

### 範例

```javascript
// 將 "photograph" 合併到 "photography"
await fetch("http://localhost:41595/api/v2/tag/merge", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        source: "photograph",
        target: "photography"
    })
}).then(r => r.json());
```

***

## Tag 屬性 <a href="#properties" id="properties"></a>

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

| 屬性       | 類型        | 說明             |
| -------- | --------- | -------------- |
| `name`   | string    | 標籤名稱           |
| `count`  | integer   | 使用此標籤的項目數量     |
| `color`  | string    | 標籤顏色（未設定時為空字串） |
| `groups` | string\[] | 標籤群組 ID 陣列     |
| `pinyin` | string    | 名稱的拼音表示        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/web-api/zh-tw/api/tag.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.