# Changelog

Eagle Web API V2 changelog, documenting all notable changes.

{% hint style="info" %}
Looking for the V1 API changelog? Visit the [legacy V1 API documentation](https://api.eagle.cool/).
{% endhint %}

***

## Smart Folder API — Eagle 4.0 Build 22

{% hint style="danger" %}
**This feature is not yet released**: This feature requires Eagle 4.0 Build 22 or later. Please follow the Eagle website for release updates.
{% endhint %}

New Smart Folder CRUD endpoints and rule query functionality:

* `GET /api/v2/smartFolder/get` — List all smart folders
* `POST /api/v2/smartFolder/create` — Create a smart folder
* `POST /api/v2/smartFolder/update` — Update a smart folder
* `POST /api/v2/smartFolder/remove` — Delete a smart folder
* `GET /api/v2/smartFolder/getItems` — Get matching items
* `GET /api/v2/smartFolder/getRules` — Get available rule schema

### Item API Enhancement

* `POST /api/v2/item/get` added `smartFolders` parameter, combinable with other filters

***

## Comment API — Eagle 4.0 Build 22

{% hint style="danger" %}
**This feature is not yet released**: This feature requires Eagle 4.0 Build 22 or later. Please follow the Eagle website for release updates.
{% endhint %}

New Comment CRUD endpoints for managing image rect annotations and video timeline notes:

* `GET /api/v2/item/getComments` — Get all comments for an item
* `POST /api/v2/item/addComment` — Add an image rect comment or video timestamp comment
* `POST /api/v2/item/updateComment` — Update an existing comment
* `POST /api/v2/item/removeComment` — Remove a comment

***

## V2 API — Initial Release

The V2 API (`/api/v2/...`) is a comprehensive replacement for the V1 API, built on top of Eagle's Plugin API capabilities. Key features:

### New Capabilities (vs V1)

* **Full-text search** — `POST /api/v2/item/query` with advanced query syntax (AND, OR, NOT, phrases)
* **AI semantic search** — Search by text description (`searchByText`), image similarity (`searchByBase64`, `searchByItemId`)
* **Tag management** — Create, rename, and merge tags; manage tag groups
* **Folder management** — Create, move, rename, and organize folders
* **Automatic pagination** — All list endpoints return paginated results by default (`offset` / `limit`)
* **Field selection** — Use the `fields` parameter on item list to return only needed data

### Endpoints

| Section   | Endpoints                                                                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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`                       |

### Pagination

All list endpoints use automatic pagination:

* Default limit: `50`
* Maximum limit: `1000`
* Response includes `total`, `offset`, and `limit` metadata


---

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