> 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/ja-jp/api/tag.md).

# Tag

Tag API を使用すると、Eagle ライブラリ内のタグの一覧表示、名前変更、統合を行うことができます。

## エンドポイント一覧

| メソッド | エンドポイント                      | 説明           |
| ---- | ---------------------------- | ------------ |
| 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());
```

***

## タグのプロパティ <a href="#properties" id="properties"></a>

API から返されるタグには以下のプロパティが含まれます：

| プロパティ    | 型         | 説明                |
| -------- | --------- | ----------------- |
| `name`   | string    | タグ名               |
| `count`  | integer   | このタグを使用しているアイテム数  |
| `color`  | string    | タグの色（未設定の場合は空文字列） |
| `groups` | string\[] | タググループ ID の配列     |
| `pinyin` | string    | タグ名のピンイン表記        |