### Quick Start Examples

Source: https://developer.eagle.cool/web-api

A collection of common API calls to get started quickly, including checking app info, listing items, searching items by tag, full-text search, and AI semantic search.

```APIDOC
## Quick Start

```javascript
// Check if Eagle is running
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());

// Get library info
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

// List first 50 items
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// Search items by tag
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"] })
}).then(r => r.json());

// Full-text search
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "sunset landscape" })
}).then(r => r.json());

// AI semantic search
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "an orange cat", options: { limit: 10 } })
}).then(r => r.json());
```
```

--------------------------------

### Quick Start API Calls

Source: https://developer.eagle.cool/web-api

A collection of common API calls for quickly getting started with Eagle. Includes checking app status, getting library info, listing items, searching by tag, full-text search, and AI semantic search.

```javascript
// Check if Eagle is running
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());

// Get library info
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

// List first 50 items
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// Search items by tag
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"] })
}).then(r => r.json());

// Full-text search
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "sunset landscape" })
}).then(r => r.json());

// AI semantic search
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "an orange cat", options: { limit: 10 } })
}).then(r => r.json());
```

--------------------------------

### POST /api/v2/item/get Examples

Source: https://developer.eagle.cool/web-api/api/item

Examples demonstrating how to retrieve items with different filtering criteria such as tags, IDs, file extensions, and folders.

```APIDOC
## POST /api/v2/item/get

### Description
Retrieves items based on specified filters like tags, IDs, file extensions, and folders. Supports field selection for optimized responses.

### Method
POST

### Endpoint
/api/v2/item/get

### Request Body
- **tags** (string[]) - Optional - Tags to filter items by.
- **ids** (string[]) - Optional - Specific item IDs to retrieve.
- **ext** (string) - Optional - File extension to filter by (e.g., "jpg").
- **folders** (string[]) - Optional - Folder IDs to filter items within.
- **fields** (string[]) - Optional - Specifies which fields to return in the response (e.g., ["id", "name", "tags"]).
- **offset** (integer) - Optional - Pagination offset.
- **limit** (integer) - Optional - Maximum number of items to return.
- **smartFolders** (string[]) - Optional - Smart folder IDs to filter items by.

### Request Example
```json
{
  "tags": ["design", "inspiration"],
  "limit": 20
}
```

### Request Example
```json
{
  "ids": ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"]
}
```

### Request Example
```json
{
  "ext": "jpg",
  "folders": ["FOLDER_ID"],
  "fields": ["id", "name", "tags"],
  "offset": 0,
  "limit": 100
}
```

### Request Example
```json
{
  "smartFolders": ["SMART_FOLDER_ID"],
  "tags": ["cat"],
  "limit": 20
}
```
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://developer.eagle.cool/web-api/get-started

To get information not explicitly on a page, make an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and self-contained. The response will include an answer and relevant excerpts.

```http
GET https://developer.eagle.cool/web-api/get-started.md?ask=<question>
```

--------------------------------

### Local Access Example

Source: https://developer.eagle.cool/web-api

Example of how to access the API from the same machine where Eagle is running. No authentication token is required for local access.

```APIDOC
## Local Access Example

### Description
This example demonstrates how to make a request to the `/library/info` endpoint when accessing the API from the same machine where Eagle is running. No authentication token is needed for local requests.

### Method
GET

### Endpoint
`http://localhost:41595/api/v2/library/info`

### Request Example
```javascript
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());
```

### Response
#### Success Response (200)
```json
{
    "status": "success",
    "data": { ... }
}
```
```

--------------------------------

### Query Documentation Dynamically

Source: https://developer.eagle.cool/web-api/get-started/playground

Perform an HTTP GET request to the documentation URL with the 'ask' query parameter to get answers to specific questions.

```http
GET https://developer.eagle.cool/web-api/get-started/playground.md?ask=<question>
```

--------------------------------

### Query Documentation with HTTP GET

Source: https://developer.eagle.cool/web-api/api

To get information not explicitly present on a page, perform an HTTP GET request to the page URL with an 'ask' query parameter containing your question in natural language.

```http
GET https://developer.eagle.cool/web-api/api.md?ask=<question>
```

--------------------------------

### Query Documentation via GET Request

Source: https://developer.eagle.cool/web-api/changelog

To get additional information not directly present on the page, perform an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and in natural language.

```http
GET https://developer.eagle.cool/web-api/changelog.md?ask=<question>
```

--------------------------------

### Get Library Info (Remote Access)

Source: https://developer.eagle.cool/web-api

Example of fetching library information using the Web API from a different device on the local network. An API token must be included in the request.

```javascript
// Remote access with token
const TOKEN = "f366c476-7533-4f33-b454-2bc720a1d0ea";

await fetch(`http://192.168.1.100:41595/api/v2/library/info?token=${TOKEN}`)
    .then(r => r.json());
```

--------------------------------

### Remote Access Example

Source: https://developer.eagle.cool/web-api

Example of how to access the API from another device on your local network. An API Token must be included in the request.

```APIDOC
## Remote Access Example

### Description
This example shows how to access the Eagle API from a different device on your local network. You must include your API Token as a query parameter for authentication.

### Method
GET / POST

### Endpoint
`http://<your-eagle-ip>:41595/api/v2/<endpoint>?token=<YOUR_API_TOKEN>`

### Parameters
#### Query Parameters
- **token** (string) - Required - Your unique API Token.

### Request Example (GET)
```javascript
const TOKEN = "f366c476-7533-4f33-b454-2bc720a1d0ea"; // Replace with your actual token

await fetch(`http://192.168.1.100:41595/api/v2/library/info?token=${TOKEN}`)
    .then(r => r.json());
```

### Request Example (POST)
```javascript
const TOKEN = "f366c476-7533-4f33-b454-2bc720a1d0ea"; // Replace with your actual token

await fetch(`http://192.168.1.100:41595/api/v2/item/get?token=${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"], limit: 20 })
}).then(r => r.json());
```

### Response
#### Success Response (200)
```json
{
    "status": "success",
    "data": { ... }
}
```
```

--------------------------------

### Query Documentation Dynamically

Source: https://developer.eagle.cool/web-api/api/tag-group

To get information not explicitly present on the page, perform an HTTP GET request with the 'ask' query parameter. The question should be specific and self-contained.

```http
GET https://developer.eagle.cool/web-api/api/tag-group.md?ask=<question>
```

--------------------------------

### Fetch Application Info

Source: https://developer.eagle.cool/web-api/api/app

Example of how to fetch application information using the fetch API. Ensure the correct port is used.

```javascript
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());
```

--------------------------------

### Check if AI Search is Installed

Source: https://developer.eagle.cool/web-api/api/ai-search

Use this endpoint to verify if the AI Search plugin is installed. It returns a boolean indicating the installation status.

```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isInstalled").then(r => r.json());
```

--------------------------------

### Check if AI Search is starting up

Source: https://developer.eagle.cool/web-api/api/ai-search

Checks whether the AI Search service is currently starting up. Requires the AI Search Plugin.

```APIDOC
## GET /api/v2/aiSearch/isStarting

### Description
Check whether the AI Search service is currently starting up.

### Method
GET

### Endpoint
/api/v2/aiSearch/isStarting

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.
- **data** (boolean) - True if AI Search is starting up, false otherwise.

### Response Example
```json
{
    "status": "success",
    "data": false
}
```
```

--------------------------------

### Query Documentation Dynamically

Source: https://developer.eagle.cool/web-api/api/smart-folder

To get additional information not explicitly present, perform an HTTP GET request on the current page URL with the 'ask' query parameter. The question should be specific and in natural language.

```http
GET https://developer.eagle.cool/web-api/api/smart-folder.md?ask=<question>
```

--------------------------------

### Check if AI Search is Starting Up

Source: https://developer.eagle.cool/web-api/api/ai-search

Determine if the AI Search service is currently in the process of starting. Returns a boolean.

```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isStarting").then(r => r.json());
```

--------------------------------

### Recommended AI Search Workflow

Source: https://developer.eagle.cool/web-api/api/ai-search

This example demonstrates a recommended workflow for using the AI Search API. It includes checking if the AI Search service is ready before performing a text-based search.

```javascript
// Step 1: Verify AI Search is ready
const { data: isReady } = await fetch("http://localhost:41595/api/v2/aiSearch/isReady")
    .then(r => r.json());

if (isReady) {
    // Step 2: Perform search
    const results = await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ query: "sunset landscape", options: { limit: 10 } })
    }).then(r => r.json());

    console.log(results.data.results);
}
```

--------------------------------

### Check if AI Search is installed

Source: https://developer.eagle.cool/web-api/api/ai-search

Checks whether the AI Search plugin is installed. Requires the AI Search Plugin.

```APIDOC
## GET /api/v2/aiSearch/isInstalled

### Description
Check whether the AI Search plugin is installed.

### Method
GET

### Endpoint
/api/v2/aiSearch/isInstalled

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.
- **data** (boolean) - True if the AI Search plugin is installed, false otherwise.

### Response Example
```json
{
    "status": "success",
    "data": true
}
```
```

--------------------------------

### Get items with various filters

Source: https://developer.eagle.cool/web-api/api/item

Use the `get` endpoint to retrieve items based on tags, IDs, file extensions, or folders. Specify `fields` to optimize response size.

```javascript
// Filter by tags
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        tags: ["design", "inspiration"],
        limit: 20
    })
}).then(r => r.json());
```

```javascript
// Get items by multiple IDs
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"]
    })
}).then(r => r.json());
```

```javascript
// Filter JPG files in a specific folder, return only id and name
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ext: "jpg",
        folders: ["FOLDER_ID"],
        fields: ["id", "name", "tags"],
        offset: 0,
        limit: 100
    })
}).then(r => r.json());
```

```javascript
// Filter with smart folders
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolders: ["SMART_FOLDER_ID"],
        tags: ["cat"],
        limit: 20
    })
}).then(r => r.json());
```

--------------------------------

### Get Items in Smart Folder (GET)

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves items that match the smart folder's filter conditions. Supports sorting and field selection.

```APIDOC
## GET /api/v2/smartFolder/getItems

### Description
Get items that match the smart folder's filter conditions.

### Method
GET

### Endpoint
/api/v2/smartFolder/getItems

### Parameters
#### Query Parameters
- **smartFolderId** (string) - Required - Smart folder ID
- **orderBy** (string) - Optional - Sort field
- **fields** (string) - Optional - Comma-separated list of fields to return

### Response
#### Success Response (200)
```json
{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}
```

### Response Example
```json
{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}
```
```

--------------------------------

### Get Smart Folder Items (GET)

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves items associated with a smart folder using query parameters. You can specify the smart folder ID and optionally sort fields or select specific fields to return.

```javascript
// Get all items in a smart folder
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1")
    .then(r => r.json());

// Return only specific fields
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1&fields=id,name,tags")
    .then(r => r.json());
```

--------------------------------

### Get Smart Folder Items (POST)

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves items associated with a smart folder by sending parameters in the request body. This method is an alternative to the GET endpoint and allows for more complex parameter structures.

```javascript
await fetch("http://localhost:41595/api/v2/smartFolder/getItems", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolderId: "LRK3AQGN7VCB1",
        fields: ["id", "name", "ext", "width", "height"]
    })
}).then(r => r.json());
```

--------------------------------

### List Folders with GET

Source: https://developer.eagle.cool/web-api/api/folder

Use this endpoint to list folders with optional filtering by ID, selection status, or recent usage. Supports pagination.

```javascript
await fetch("http://localhost:41595/api/v2/folder/get").then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/folder/get?id=LRK3AQGN7VCB1").then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/folder/get?isRecent=true").then(r => r.json());
```

--------------------------------

### Dynamic Documentation Query

Source: https://developer.eagle.cool/web-api/api/item

You can query this documentation dynamically by performing an HTTP GET request to the current page URL with the `ask` query parameter.

```APIDOC
## Agent Instructions: Querying This Documentation

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/web-api/api/item.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.
```

--------------------------------

### List all tags (GET)

Source: https://developer.eagle.cool/web-api/api/tag

Retrieves a paginated list of all tags in the library. Supports filtering by name and pagination.

```APIDOC
## GET /api/v2/tag/get

### Description
List all tags in the library. Returns paginated results.

### Query Parameters
* `name` string (optional) — Filter tags by name (substring match)
* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **data** (object) - Contains the list of tags and pagination details.
  - **data** (array) - An array of tag objects.
    - **name** (string) - The name of the tag.
    - **count** (integer) - The number of items associated with the tag.
    - **color** (string) - The color associated with the tag.
    - **groups** (array) - A list of group IDs the tag belongs to.
    - **pinyin** (string) - The pinyin representation of the tag name.
  - **total** (integer) - The total number of tags available.
  - **offset** (integer) - The current pagination offset.
  - **limit** (integer) - The current pagination limit.

### Request Example
```javascript
// List all tags (first 50)
await fetch("http://localhost:41595/api/v2/tag/get").then(r => r.json());

// Filter tags by name
await fetch("http://localhost:41595/api/v2/tag/get?name=design").then(r => r.json());

// Paginate through tags
await fetch("http://localhost:41595/api/v2/tag/get?offset=50&limit=100").then(r => r.json());
```
```

--------------------------------

### GET /api/v2/app/info

Source: https://developer.eagle.cool/web-api/api/app

Retrieves information about the running Eagle application, including version numbers and platform details.

```APIDOC
## GET /api/v2/app/info

### Description
Returns information about the running Eagle application, including version numbers and platform details.

### Method
GET

### Endpoint
/api/v2/app/info

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the request, typically "success".
- **data** (object) - Contains the application information.
  - **version** (string) - Eagle version number (e.g., "4.0.0").
  - **prereleaseVersion** (string | null) - Pre-release version identifier, or null for stable.
  - **buildVersion** (string | null) - Build version identifier (e.g., "build12").
  - **platform** (string) - Operating system: "win32" (Windows) or "darwin" (macOS).

### Request Example
```javascript
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());
```

### Response Example
```json
{
    "status": "success",
    "data": {
        "version": "4.0.0",
        "prereleaseVersion": null,
        "buildVersion": "build12",
        "platform": "win32"
    }
}
```
```

--------------------------------

### GET /api/v2/library/info

Source: https://developer.eagle.cool/web-api/api/library

Retrieves metadata about the currently open Eagle library, including its name, path, and configuration details.

```APIDOC
## GET /api/v2/library/info

### Description
Returns metadata about the currently open Eagle library, including its name, path, and configuration.

### Method
GET

### Endpoint
/api/v2/library/info

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **data** (object) - Contains the library metadata.
  - **name** (string) - The display name of the library.
  - **path** (string) - The full path to the library file.
  - **modificationTime** (integer) - The timestamp of the last modification.
  - **applicationVersion** (string) - The Eagle version that created the library.
  - **folders** (array) - An array representing the top-level folder structure.
  - **smartFolders** (array) - An array representing smart folder configurations.
  - **quickAccess** (array) - An array of quick access items.
  - **tagGroups** (array) - An array of tag group definitions.

### Request Example
```javascript
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());
```
```

--------------------------------

### GET /api/v2/library/history

Source: https://developer.eagle.cool/web-api/api/library

Fetches a paginated list of recently opened libraries.

```APIDOC
## GET /api/v2/library/history

### Description
Get the list of recently opened libraries. Returns paginated results.

### Method
GET

### Endpoint
/api/v2/library/history

### Query Parameters
- **offset** (integer) - Optional. Pagination offset, default `0`.
- **limit** (integer) - Optional. Pagination limit, default `50`, max `1000`.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **data** (object) - Contains the list of libraries and pagination info.
  - **data** (array) - An array of library objects, each with `name` and `path`.
  - **total** (integer) - The total number of libraries in the history.
  - **offset** (integer) - The current pagination offset.
  - **limit** (integer) - The current pagination limit.

### Examples
```javascript
// Get default paginated list
await fetch("http://localhost:41595/api/v2/library/history").then(r => r.json());

// With custom pagination
await fetch("http://localhost:41595/api/v2/library/history?offset=0&limit=10").then(r => r.json());
```
```

--------------------------------

### List All Tags (GET)

Source: https://developer.eagle.cool/web-api/api/tag

Use this endpoint to retrieve a paginated list of all tags. You can filter by name and control pagination with offset and limit.

```javascript
await fetch("http://localhost:41595/api/v2/tag/get").then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/tag/get?name=design").then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/tag/get?offset=50&limit=100").then(r => r.json());
```

--------------------------------

### POST Request with Token (Remote Access)

Source: https://developer.eagle.cool/web-api

Example of making a POST request to the Web API from a remote device, including the API token and a JSON body. This demonstrates how to send data for operations like item retrieval.

```javascript
// Also works with POST requests
await fetch(`http://192.168.1.100:41595/api/v2/item/get?token=${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"], limit: 20 })
}).then(r => r.json());
```

--------------------------------

### Get Application Info Response

Source: https://developer.eagle.cool/web-api/api/app

This JSON structure represents the response when requesting information about the running Eagle application.

```json
{
    "status": "success",
    "data": {
        "version": "4.0.0",
        "prereleaseVersion": null,
        "buildVersion": "build12",
        "platform": "win32"
    }
}
```

--------------------------------

### List Smart Folders (POST)

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves a list of smart folders using a POST request, allowing filter parameters to be sent in the request body. This is an alternative to the GET method for listing smart folders.

```APIDOC
## POST /api/v2/smartFolder/get

### Description
Same as GET, but accepts filter parameters in a JSON body.

### Request Body
* `id` string (optional) — Smart folder ID
* `ids` string[] (optional) — Array of smart folder IDs

### Request Example
```javascript
// Get smart folders by multiple IDs
await fetch("http://localhost:41595/api/v2/smartFolder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["SMART_FOLDER_ID_1", "SMART_FOLDER_ID_2"]
    })
}).then(r => r.json());
```
```

--------------------------------

### Get Library Metadata

Source: https://developer.eagle.cool/web-api/api/library

Fetch metadata for the currently open Eagle library. This includes its name, path, and configuration details.

```javascript
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());
```

--------------------------------

### List Folders (GET)

Source: https://developer.eagle.cool/web-api/api/folder

Retrieves a list of folders with optional filtering and pagination. Supports filtering by ID, multiple IDs, selection status, and recent usage.

```APIDOC
## GET /api/v2/folder/get

### Description
List folders with optional filtering. Returns paginated results.

### Method
GET

### Endpoint
/api/v2/folder/get

### Parameters
#### Query Parameters
- **id** (string) - Optional - Return a single folder by ID
- **ids** (string) - Optional - Comma-separated folder IDs
- **isSelected** (boolean) - Optional - Return the currently selected folder
- **isRecent** (boolean) - Optional - Return recently used folders
- **offset** (integer) - Optional - Pagination offset, default `0`
- **limit** (integer) - Optional - Pagination limit, default `50`, max `1000`

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.
- **data** (object) - Contains the list of folders and pagination details.
  - **data** (array) - Array of folder objects.
    - **id** (string) - Unique identifier for the folder.
    - **name** (string) - Name of the folder.
    - **description** (string) - Description of the folder.
    - **children** (array) - List of child folder IDs.
    - **modificationTime** (integer) - Timestamp of the last modification.
    - **tags** (array) - List of tags associated with the folder.
    - **iconColor** (string) - Color of the folder icon.
    - **imageCount** (integer) - Number of images within the folder.
  - **total** (integer) - Total number of folders available.
  - **offset** (integer) - Current pagination offset.
  - **limit** (integer) - Current pagination limit.

### Response Example
```json
{
    "status": "success",
    "data": {
        "data": [
            {
                "id": "LRK3AQGN7VCB1",
                "name": "Design References",
                "description": "UI/UX design references",
                "children": [],
                "modificationTime": 1700000000000,
                "tags": [],
                "iconColor": "blue",
                "imageCount": 42
            }
        ],
        "total": 25,
        "offset": 0,
        "limit": 50
    }
}
```

### Examples
```javascript
// List all folders (first 50)
await fetch("http://localhost:41595/api/v2/folder/get").then(r => r.json());

// Get a single folder by ID
await fetch("http://localhost:41595/api/v2/folder/get?id=LRK3AQGN7VCB1").then(r => r.json());

// Get recently used folders
await fetch("http://localhost:41595/api/v2/folder/get?isRecent=true").then(r => r.json());
```
```

--------------------------------

### List Folders with POST

Source: https://developer.eagle.cool/web-api/api/folder

This endpoint provides the same functionality as the GET /api/v2/folder/get endpoint but accepts filter parameters within the JSON request body.

```javascript
await fetch("http://localhost:41595/api/v2/folder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["FOLDER_ID_1", "FOLDER_ID_2"]
    })
}).then(r => r.json());
```

--------------------------------

### List Folders (POST)

Source: https://developer.eagle.cool/web-api/api/folder

Retrieves a list of folders using POST request, allowing filter parameters to be passed in the request body. This is an alternative to the GET method for listing folders.

```APIDOC
## POST /api/v2/folder/get

### Description
Same as GET, but accepts filter parameters in the JSON body.

### Method
POST

### Endpoint
/api/v2/folder/get

### Parameters
#### Request Body
- **id** (string) - Optional - Folder ID
- **ids** (string[]) - Optional - Array of folder IDs
- **isSelected** (boolean) - Optional - Currently selected folder
- **isRecent** (boolean) - Optional - Recently used folders
- **offset** (integer) - Optional - Pagination offset, default `0`
- **limit** (integer) - Optional - Pagination limit, default `50`, max `1000`

### Request Example
```javascript
// Get folders by multiple IDs
await fetch("http://localhost:41595/api/v2/folder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["FOLDER_ID_1", "FOLDER_ID_2"]
    })
}).then(r => r.json());
```
```

--------------------------------

### Get Matching Items

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves items that match the conditions of a specified smart folder. This can be done by providing the smart folder ID or its conditions directly in the request body.

```APIDOC
## GET /api/v2/smartFolder/getItems

### Description
Get matching items.

### Query Parameters
* `id` string (required) — Smart folder ID
* `limit` number (optional) — Maximum number of items to return
* `offset` number (optional) — Number of items to skip

### Response
#### Success Response (200)
- `status` string - Indicates the success of the operation.
- `data` array - An array of items matching the smart folder criteria.
- `total` number - The total number of matching items.
```

```APIDOC
## POST /api/v2/smartFolder/getItems

### Description
Get matching items (request body).

### Request Body
* `id` string (optional) — Smart folder ID
* `conditions` Object[] (optional) — Filter conditions to match items against. If `id` is provided, `conditions` are ignored.
* `limit` number (optional) — Maximum number of items to return
* `offset` number (optional) — Number of items to skip

### Response
#### Success Response (200)
- `status` string - Indicates the success of the operation.
- `data` array - An array of items matching the smart folder criteria.
- `total` number - The total number of matching items.
```

--------------------------------

### Get Items in Smart Folder (POST)

Source: https://developer.eagle.cool/web-api/api/smart-folder

Retrieves items that match the smart folder's filter conditions using a JSON body for parameters. Supports sorting and field selection.

```APIDOC
## POST /api/v2/smartFolder/getItems

### Description
Same as GET, but accepts parameters in a JSON body.

### Method
POST

### Endpoint
/api/v2/smartFolder/getItems

### Parameters
#### Request Body
- **smartFolderId** (string) - Required - Smart folder ID
- **orderBy** (string) - Optional - Sort field
- **fields** (string[]) - Optional - Fields to return

### Request Example
```json
{
    "smartFolderId": "LRK3AQGN7VCB1",
    "fields": ["id", "name", "ext", "width", "height"]
}
```

### Response
#### Success Response (200)
Returns a list of items matching the smart folder's criteria.

### Response Example
```json
{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}
```
```

--------------------------------

### Get starred tags (GET)

Source: https://developer.eagle.cool/web-api/api/tag

Retrieves a paginated list of starred (pinned) tags. Supports pagination.

```APIDOC
## GET /api/v2/tag/getStarredTags

### Description
Get starred (pinned) tags. Returns paginated results.

### Query Parameters
* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **data** (object) - Contains the list of tags and pagination details.
  - **data** (array) - An array of tag objects.
    - **name** (string) - The name of the tag.
    - **count** (integer) - The number of items associated with the tag.
    - **color** (string) - The color associated with the tag.
    - **groups** (array) - A list of group IDs the tag belongs to.
    - **pinyin** (string) - The pinyin representation of the tag name.
  - **total** (integer) - The total number of tags available.
  - **offset** (integer) - The current pagination offset.
  - **limit** (integer) - The current pagination limit.

### Example
```javascript
await fetch("http://localhost:41595/api/v2/tag/getStarredTags").then(r => r.json());
```
```

--------------------------------

### List Items with Default Parameters

Source: https://developer.eagle.cool/web-api/api/item

Fetches the first 50 items using default pagination settings. This is the most basic way to list items.

```javascript
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());
```

--------------------------------

### Get recently used tags (GET)

Source: https://developer.eagle.cool/web-api/api/tag

Retrieves a paginated list of recently used tags. Supports pagination.

```APIDOC
## GET /api/v2/tag/getRecentTags

### Description
Get recently used tags. Returns paginated results.

### Query Parameters
* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **data** (object) - Contains the list of tags and pagination details.
  - **data** (array) - An array of tag objects.
    - **name** (string) - The name of the tag.
    - **count** (integer) - The number of items associated with the tag.
    - **color** (string) - The color associated with the tag.
    - **groups** (array) - A list of group IDs the tag belongs to.
    - **pinyin** (string) - The pinyin representation of the tag name.
  - **total** (integer) - The total number of tags available.
  - **offset** (integer) - The current pagination offset.
  - **limit** (integer) - The current pagination limit.

### Example
```javascript
await fetch("http://localhost:41595/api/v2/tag/getRecentTags").then(r => r.json());
```
```

--------------------------------

### Create Root Folder

Source: https://developer.eagle.cool/web-api/api/folder

Use this endpoint to create a new folder at the root level of your library. Requires a name, and optionally accepts a description.

```javascript
await fetch("http://localhost:41595/api/v2/folder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "My New Folder" })
}).then(r => r.json());
```

--------------------------------

### Add Item via URL, Path, or Bookmark

Source: https://developer.eagle.cool/web-api/api/item

Use this endpoint to add a single item to the system. You can provide a URL for remote content, a local file path, or a bookmark URL. Ensure the `Content-Type` header is set to `application/json`.

```javascript
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://example.com/photo.jpg",
        name: "Example Photo",
        tags: ["downloaded", "example"],
        folders: ["FOLDER_ID"]
    })
}).then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        path: "C:\\Users\\User\\Downloads\\design.png",
        name: "My Design",
        tags: ["design"]
    })
}).then(r => r.json());
```

```javascript
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        bookmarkURL: "https://www.example.com",
        name: "Example Site",
        tags: ["bookmark"]
    })
}).then(r => r.json());
```

--------------------------------

### Create Smart Folder

Source: https://developer.eagle.cool/web-api/api/smart-folder

Use this endpoint to create a new smart folder. You must provide a name and conditions, and can optionally specify a description, icon, icon color, and parent folder.

```javascript
// Create a smart folder for large PNG images
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "Large PNGs",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] },
                    { "property": "type", "method": "equal", "value": "png" }
                ],
                "match": "AND"
            }
        ],
        iconColor: "blue"
    })
}).then(r => r.json());
```

--------------------------------

### Create Folder

Source: https://developer.eagle.cool/web-api/api/folder

Creates a new folder in the library. You can specify the folder's name, description, and parent folder.

```APIDOC
## POST /api/v2/folder/create

### Description
Create a new folder in the library.

### Method
POST

### Endpoint
/api/v2/folder/create

### Parameters
#### Request Body
- **name** (string) - Required - Folder name
- **description** (string) - Optional - Folder description
- **parent** (string) - Optional - Parent folder ID. If omitted, creates at root level.

### Response
Returns the newly created folder object.

#### Success Response (200)
- **status** (string) - Indicates the status of the operation.
- **data** (object) - Contains the newly created folder object.
  - **id** (string) - Unique identifier for the new folder.
  - **name** (string) - Name of the new folder.
  - **description** (string) - Description of the new folder.
  - **children** (array) - List of child folder IDs.
  - **modificationTime** (integer) - Timestamp of the last modification.
  - **tags** (array) - List of tags associated with the folder.

### Response Example
```json
{
    "status": "success",
    "data": {
        "id": "NEW_FOLDER_ID",
        "name": "My New Folder",
        "description": "",
        "children": [],
        "modificationTime": 1700000000000,
        "tags": []
    }
}
```

### Examples
```javascript
// Create a root-level folder
await fetch("http://localhost:41595/api/v2/folder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "My New Folder" })
}).then(r => r.json());

// Create a subfolder
await fetch("http://localhost:41595/api/v2/folder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "Subfolder",
        description: "A subfolder for organizing",
        parent: "PARENT_FOLDER_ID"
    })
}).then(r => r.json());
```
```

--------------------------------

### Iterating Through All Items with Pagination

Source: https://developer.eagle.cool/web-api

Demonstrates how to fetch all items by making sequential requests, incrementing the offset until the returned data array is smaller than the limit. This is useful for retrieving large datasets.

```javascript
// Page 1: items 0-49
const page1 = await fetch("http://localhost:41595/api/v2/item/get?limit=50").then(r => r.json());

// Page 2: items 50-99
const page2 = await fetch("http://localhost:41595/api/v2/item/get?offset=50&limit=50").then(r => r.json());

// Continue until data.data.length < limit (last page)
```

--------------------------------

### Create Smart Folder

Source: https://developer.eagle.cool/web-api/api/smart-folder

Creates a new smart folder with specified name, conditions, and optional metadata. The conditions define the criteria for assets to be included in the folder.

```APIDOC
## POST /api/v2/smartFolder/create

### Description
Create a new smart folder.

### Request Body
* `name` string (required) — Smart folder name
* `conditions` Object[] (required) — Filter conditions (see [Conditions Format](#conditions) below)
* `description` string (optional) — Description
* `icon` string (optional) — Icon
* `iconColor` string (optional) — Icon color. Allowed values: `red`, `orange`, `yellow`, `green`, `aqua`, `blue`, `purple`, `pink`
* `parent` string (optional) — Parent smart folder ID. If omitted, creates at root level.

### Response
Returns the newly created smart folder object.
#### Success Response (200)
- `status` string - Indicates the success of the operation.
- `data` object - The newly created smart folder object.
  - `id` string - The unique identifier for the smart folder.
  - `name` string - The name of the smart folder.
  - `conditions` array - The filtering conditions for the smart folder.
  - `description` string - A description of the smart folder.
  - `icon` string - The icon associated with the smart folder.
  - `iconColor` string - The color of the icon.
  - `children` array - Child smart folders.
  - `modificationTime` number - The last modification timestamp.
  - `imageCount` number - The number of items matching the smart folder conditions.

### Request Example
```javascript
// Create a smart folder for large PNG images
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "Large PNGs",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] },
                    { "property": "type", "method": "equal", "value": "png" }
                ],
                "match": "AND"
            }
        ],
        iconColor: "blue"
    })
}).then(r => r.json());
```
```

--------------------------------

### GET /api/v2/library/icon

Source: https://developer.eagle.cool/web-api/api/library

Retrieves the icon for a specified library.

```APIDOC
## GET /api/v2/library/icon

### Description
Get the icon for a library.

### Method
GET

### Endpoint
/api/v2/library/icon

### Query Parameters
- **libraryPath** (string) - Required. Path to the library.

### Response
Returns the icon image data.

### Example
```javascript
await fetch("http://localhost:41595/api/v2/library/icon?libraryPath=D%3A%5CEagle%20Libraries%5CMy%20Design%20Library.library")
    .then(r => r.blob());
```
```