# Changelog

Eagle Plugin API changelog, documenting all important feature changes since the first Plugin API version.

{% hint style="info" %}
Update: Eagle 4.0 Build12 has been officially released. Features marked "Eagle 4.0 Build12+" are now available. If you are on an older version, please upgrade to 4.0 build12 or later.
{% endhint %}

## March 24, 2026

### 📄 Item API Enhancement

**New Feature: Comment CRUD API (Eagle 4.0 build22+)**

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build22 or later.
{% endhint %}

* Added [`item.comments`](https://developer.eagle.cool/plugin-api/api/item#comments-object) read-only property to access item comments/annotations
* Added [`item.addComment(commentData)`](https://developer.eagle.cool/plugin-api/api/item#add-comment) method for adding image rect comments or video timestamp comments
* Added [`item.updateComment(commentId, updateData)`](https://developer.eagle.cool/plugin-api/api/item#update-comment) method for updating existing comments
* Added [`item.removeComment(commentId)`](https://developer.eagle.cool/plugin-api/api/item#remove-comment) method for removing comments

```javascript
let item = await eagle.item.getById('item_id');

// Read comments
console.log(item.comments);

// Add image rect comment
await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "Face area" });

// Add video timestamp comment
await item.addComment({ duration: 65.5, annotation: "Important scene" });

// Update comment
await item.updateComment('comment_id', { annotation: "Updated text" });

// Remove comment
await item.removeComment('comment_id');
```

### 📁 Smart Folder API

**New Feature: Smart Folder CRUD API (Eagle 4.0 build22+)**

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build22 or later.
{% endhint %}

* Added [`eagle.smartFolder`](https://developer.eagle.cool/plugin-api/api/smart-folder) module with full smart folder management support
* Added `create()`, `get()`, `getAll()`, `getById()`, `getByIds()`, `remove()` methods
* Added `getRules()` method to get available filter rule schema
* Added `rule()` fluent builder and `Condition.create()` helper
* SmartFolder instances support `save()` and `getItems()` methods

```javascript
// Using the fluent builder
const sf = await eagle.smartFolder.create({
    name: 'Large Images',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// Query rule schema
const rules = await eagle.smartFolder.getRules();

// Get matching items
const items = await sf.getItems();
```

### 🔧 Manifest Configuration Enhancement

**New Feature: followCursor Window Positioning (Eagle 4.0 build22+)**

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build22 or later.
{% endhint %}

* Added `followCursor` manifest setting — when enabled, the window automatically positions near the cursor
* Ideal for tool-type plugins that require quick interaction, minimizing the distance for user interaction
* When enabled, the window does not remember its position and follows the cursor each time it opens

```json
{
    "main": {
        "followCursor": true
    }
}
```

## January 22, 2026

### 💻 App API Enhancement

**New Feature: Show Main Window (Eagle 4.0 build18+)**

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build18 or later.
{% endhint %}

* Added [`eagle.app.show()`](https://developer.eagle.cool/plugin-api/api/app#show) method, allowing plugins to bring the Eagle main application window to the front and display it on top

```javascript
// Bring Eagle main window to the front
await eagle.app.show();
```

### 📄 Item API Enhancement

**New Feature: Modify Import Time (Eagle 4.0 build18+)**

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build18 or later.
{% endhint %}

* [`item.importedAt`](https://developer.eagle.cool/plugin-api/api/item#importedat-interger) property now supports modification, allowing plugins to customize file import time
* Useful for batch importing historical files, data migration, and other scenarios requiring preservation of original timestamps

```javascript
// Modify import time
item.importedAt = new Date('2024-01-01').getTime();
await item.save();
```

## January 9, 2026

### 🔍 AI Search Semantic Search API

**New Feature: AI Semantic Search Integration (Eagle 4.0 build18+)**

* Added [`eagle.extraModule.aiSearch`](https://developer.eagle.cool/plugin-api/extra-module/ai-search) module, providing AI semantic search capabilities
* **Status Query Methods**:
  * `isInstalled()` - Check if AI Search plugin is installed
  * `isReady()` - Check if service is ready
  * `isStarting()` - Check if service is starting
  * `isSyncing()` - Check if data is syncing
* **Service Control Methods**:
  * `open()` - Open AI Search plugin
  * `checkServiceHealth()` - Check service health status
  * `getSyncStatus()` - Get detailed sync status
* **Search Methods**:
  * `searchByText(query, options)` - Text semantic search
  * `searchByBase64(base64, options)` - Base64 image search
  * `searchByItemId(itemId, options)` - Search similar images by item ID

```javascript
const aiSearch = eagle.extraModule.aiSearch;

// Check service status
if (await aiSearch.isReady()) {
    // Text semantic search
    const result = await aiSearch.searchByText('an orange cat', { limit: 10 });

    // Results contain complete Item objects
    result.results.forEach(r => {
        console.log(`${r.item.name} - Similarity: ${(r.score * 100).toFixed(1)}%`);
    });
}
```

## January 8, 2026

### 🏷️ TagGroup/Tag API Incremental Operations

**New Feature: Incremental Tag Group Operations (Eagle 4.0 build18+)**

* [`tagGroup.addTags()`](https://developer.eagle.cool/plugin-api/api/tag-group#addtags) - Incrementally add or move tags to a group without passing the complete tags array
* [`tagGroup.removeTags()`](https://developer.eagle.cool/plugin-api/api/tag-group#removetags) - Remove specified tags from a group
* [`eagle.tag.merge()`](https://developer.eagle.cool/plugin-api/api/tag#merge) - Merge tags by renaming source tag to target tag

```javascript
// Add tags to group
await tagGroup.addTags({ tags: ['UI', 'UX'] });

// Move tags (remove from original groups)
await tagGroup.addTags({ tags: ['Branding'], removeFromSource: true });

// Remove tags from group
await tagGroup.removeTags({ tags: ['Outdated'] });

// Merge tags
const result = await eagle.tag.merge({ source: 'UI Design', target: 'UI' });
```

### 🏷️ TagGroup API Enhancement

**New Feature: Tag Group Description Property (Eagle 4.0 build18+)**

* Added `description` property to [`tagGroup`](https://developer.eagle.cool/plugin-api/api/tag-group), allowing you to add descriptive text to tag groups
* Supported in both `create()` and `save()` methods

```javascript
// Create a tag group with description
await eagle.tagGroup.create({
    name: "new group",
    description: "Group description"
});

// Modify tag group description
tagGroup.description = "New description";
await tagGroup.save();
```

## January 6, 2026

### 🏷️ Tag API Enhancement

**New Feature: Get Starred Tags (Eagle 4.0 build18+)**

* Added [`eagle.tag.getStarredTags()`](https://developer.eagle.cool/plugin-api/api/tag#starred) method to retrieve user's favorite/starred tags

```javascript
const starred = await eagle.tag.getStarredTags();
```

**Documentation Fix**

* Fixed incorrect API method name: `getRecents()` → [`getRecentTags()`](https://developer.eagle.cool/plugin-api/api/tag#dwsxw)

## August 21, 2025

### 💻 App API Enhancement

**New Feature: app.userDataPath Property (Eagle 4.0 build12+)**

* Added [`app.userDataPath`](https://developer.eagle.cool/plugin-api/api/app#ud9km) property, returns the path to the current user data directory
* Provides quick access to Eagle's user data storage location

```javascript
console.log(eagle.app.userDataPath);
// "C:\Users\User\AppData\Roaming\Eagle"
```

## August 19, 2025

### 📁 Folder API Enhancements

**New Feature: Folder parent Property Modifiable (Eagle 4.0 build12+)**

* Added [`folder.parent`](https://developer.eagle.cool/plugin-api/api/folder#woenk) property modification support, allowing dynamic adjustment of folder hierarchy
* Support for moving folders to different parent directories or root directory

```javascript
// Move to another parent folder
folder.parent = 'parent_folder_id';
await folder.save();

// Move to root directory  
folder.parent = null;
await folder.save();
```

**New Feature: Folder iconColor Property Modifiable (Eagle 4.0 build12+)**

* Changed [`folder.iconColor`](https://developer.eagle.cool/plugin-api/api/folder#woenk) property from read-only to modifiable
* Added [`eagle.folder.IconColor`](https://developer.eagle.cool/plugin-api/api/folder#static-properties) static constant object, providing predefined color options
* Supported colors: Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

```javascript
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();
```

## August 13, 2025

### 🏷️ Tag API Feature Expansion

**New Feature: Tag Filtering and Tag Class Enhancement**

* [`eagle.tag.get()`](https://developer.eagle.cool/plugin-api/api/tag#x9nu2) method added `name` parameter, supporting fuzzy search by tag name
* Tag instance added [`save()`](https://developer.eagle.cool/plugin-api/api/tag#instance-methods) method, supporting tag name modification
* Added Tag instance properties: [`name`](https://developer.eagle.cool/plugin-api/api/tag#instance-properties) (modifiable), `count`, `color`, `groups`, `pinyin`

```javascript
// Filter tags
const filteredTags = await eagle.tag.get({ name: "design" });

// Modify tag name  
tag.name = 'new-name';
await tag.save();
```

⚠️ **Note: Modifying tag names will automatically update all files using that tag**

## August 5, 2025

### 📄 Item API Performance and Selection Enhancements

**New Feature: Performance Optimization**

* [`eagle.item.get()`](https://developer.eagle.cool/plugin-api/api/item#bdcw2) added `fields` parameter, supporting selective field return for significant query performance improvement
* Added [`eagle.item.getIdsWithModifiedAt()`](https://developer.eagle.cool/plugin-api/api/item#getidswithmodifiedat) method, optimized for incremental synchronization
* Added [`modifiedAt`](https://developer.eagle.cool/plugin-api/api/item#woenk) property, recording file last modification time

```javascript
// Return only needed fields
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// Efficient incremental sync
let fileInfo = await eagle.item.getIdsWithModifiedAt();
```

**New Feature: Counting and Selection Methods**

* Added [`eagle.item.count(options)`](https://developer.eagle.cool/plugin-api/api/item#count) - conditional counting
* Added [`eagle.item.countAll()`](https://developer.eagle.cool/plugin-api/api/item#countall) - total file count
* Added [`eagle.item.countSelected()`](https://developer.eagle.cool/plugin-api/api/item#countselected) - selected file count
* Added [`eagle.item.select(itemIds)`](https://developer.eagle.cool/plugin-api/api/item#select) - programmatic file selection

```javascript
let count = await eagle.item.count({ isSelected: true });
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2']);
```

**Enhanced Feature: open() Method**

* [`eagle.item.open()`](https://developer.eagle.cool/plugin-api/api/item#yxkul) added `window` option, supporting opening files in new window

```javascript
await eagle.item.open('item_id', { window: true });
```

## July 31, 2025

### 🪟 Window API Expansion

**New Feature: Window Geometry Control**

* Added [`eagle.window.getSize()`](https://developer.eagle.cool/plugin-api/api/window#mq0dz) - get window size
* Added [`eagle.window.setBounds(bounds)`](https://developer.eagle.cool/plugin-api/api/window#setbounds-bounds) - set window bounds (position + size)
* Added [`eagle.window.getBounds()`](https://developer.eagle.cool/plugin-api/api/window#getbounds) - get window bounds information

```javascript
await eagle.window.getSize();
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 });
await eagle.window.getBounds();
```

## November 28, 2024

### 🏷️ TagGroup CRUD Operations

**New Feature: Complete Tag Group Management**

* Added [`eagle.tagGroup.create(options)`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - create new tag group
* Added [`tagGroup.save()`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - save modifications
* Added [`tagGroup.remove()`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - delete tag group

```javascript
// Create tag group
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// Modify and save
tagGroup.name = "new name";
await tagGroup.save();

// Delete group
await tagGroup.remove();
```

### 🗑️ Item Deletion Feature

**New Feature: File Trash Operations**

* Added [`item.moveToTrash()`](https://developer.eagle.cool/plugin-api/api/item#movetotrash) instance method, moving files to system trash

```javascript
let item = await eagle.item.getById('item_id');
await item.moveToTrash();
```

## July 25, 2024

### 🪟 Window API Enhancement

**New Feature: HTTP Referer Setting**

* Added [`eagle.window.setReferer(url)`](https://developer.eagle.cool/plugin-api/api/window#4a6f) method, setting referer header for subsequent network requests

```javascript
eagle.window.setReferer("https://example.com");
```

## May 10, 2024

### 🖱️ Context Menu API

**New Feature: Custom Context Menu**

* Added [`eagle.contextMenu.open()`](https://developer.eagle.cool/plugin-api/api/context-menu#tkp0d) method, supporting custom context menus
* Support for multi-level submenus, custom click events, system native styling

```javascript
eagle.contextMenu.open([
    {
        id: "edit",
        label: "Edit",
        submenu: [...],
        click: () => { ... }
    }
]);
```

### 🪟 Window API Screenshot Feature

**New Feature: Page Screenshot**

* Added [`eagle.window.capturePage(rect)`](https://developer.eagle.cool/plugin-api/api/window#yvfx9) method, supporting full page or specified area screenshots
* Returns NativeImage object, convertible to base64 or PNG buffer

```javascript
// Full page screenshot
const image = await eagle.window.capturePage();

// Specified area screenshot
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});
```

## April 17, 2024

### 🔍 Preview Plugin Feature Enhancement

**New Feature: Zoom Control Parameter**

* Preview plugin configuration added [`allowZoom`](https://developer.eagle.cool/plugin-api/get-started/plugin-types/preview) parameter, controlling whether users can zoom preview content

```json
"thumbnail": {
    "path": "thumbnail/icns.js",
    "size": 400,
    "allowZoom": false
}
```


---

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