# 更新日誌

Eagle Web API V2 更新日誌，記錄所有重要變更。

{% hint style="info" %}
在找 V1 API 的更新日誌？請前往[舊版 V1 API 文件](https://api.eagle.cool/)。
{% endhint %}

***

## Smart Folder API — Eagle 4.0 Build 22

{% hint style="danger" %}
**此功能尚未發佈**：此功能需要 Eagle 4.0 Build 22 或更高版本。詳細發佈時間請關注 Eagle 官網。
{% endhint %}

新增智慧型資料夾完整 CRUD 端點與規則查詢功能：

* `GET /api/v2/smartFolder/get` — 列出所有智慧型資料夾
* `POST /api/v2/smartFolder/create` — 建立智慧型資料夾
* `POST /api/v2/smartFolder/update` — 更新智慧型資料夾
* `POST /api/v2/smartFolder/remove` — 刪除智慧型資料夾
* `GET /api/v2/smartFolder/getItems` — 取得符合條件的項目
* `GET /api/v2/smartFolder/getRules` — 取得可用規則 schema

### Item API 增強

* `POST /api/v2/item/get` 新增 `smartFolders` 參數，可搭配其他篩選條件使用

***

## Comment API — Eagle 4.0 Build 22

{% hint style="danger" %}
**此功能尚未發佈**：此功能需要 Eagle 4.0 Build 22 或更高版本。詳細發佈時間請關注 Eagle 官網。
{% endhint %}

新增標註 CRUD 端點，用於管理圖片框選標註和影片時間軸註解：

* `GET /api/v2/item/getComments` — 取得項目的所有標註
* `POST /api/v2/item/addComment` — 新增圖片框選標註或影片時間軸註解
* `POST /api/v2/item/updateComment` — 更新現有標註
* `POST /api/v2/item/removeComment` — 移除標註

***

## V2 API — 首次發布

V2 API（`/api/v2/...`）是 V1 API 的全面替代版本，基於 Eagle 的 Plugin API 能力所建構。主要功能：

### 新功能（相比 V1）

* **全文搜尋** — `POST /api/v2/item/query` 支援進階查詢語法（AND、OR、NOT、片語）
* **AI 語義搜尋** — 透過文字描述搜尋（`searchByText`）、圖片相似度搜尋（`searchByBase64`、`searchByItemId`）
* **標籤管理** — 建立、重新命名及合併標籤；管理標籤群組
* **資料夾管理** — 建立、移動、重新命名及整理資料夾
* **自動分頁** — 所有列表端點預設回傳分頁結果（`offset` / `limit`）
* **欄位選擇** — 在項目列表中使用 `fields` 參數，只回傳所需資料

### 端點

| 分類        | 端點                                                                                                                                                       |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Item      | `get`、`query`、`countAll`、`add`、`save`、`open`、`select`、`setCustomThumbnail`、`refreshThumbnail`、`getComments`、`addComment`、`updateComment`、`removeComment` |
| Folder    | `get`、`create`、`open`、`save`                                                                                                                             |
| Tag       | `get`、`getRecentTags`、`getStarredTags`、`save`、`merge`                                                                                                    |
| Tag Group | `get`、`create`、`save`、`remove`、`addTags`、`removeTags`                                                                                                    |
| Library   | `info`                                                                                                                                                   |
| App       | `info`                                                                                                                                                   |
| AI Search | `isInstalled`、`isReady`、`isStarting`、`isSyncing`、`getSyncStatus`、`checkServiceHealth`、`searchByText`、`searchByBase64`、`searchByItemId`                   |

### 分頁

所有列表端點使用自動分頁：

* 預設限制：`50`
* 最大限制：`1000`
* 回應中包含 `total`、`offset` 和 `limit` 中繼資料


---

# 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/changelog.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.