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

# 更新日誌

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` 中繼資料