> 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.md).

# 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    | 名稱的拼音表示        |