Smart Folder

Smart Folder API allows you to list, create, update, delete smart folders, and query matching items.

This feature is not yet released: This API requires Eagle 4.0 Build 22 or later. Please follow the Eagle website for release updates.

Endpoint Overview

Method	Endpoint	Description
GET	/api/v2/smartFolder/get	List smart folders
POST	/api/v2/smartFolder/get	List smart folders (request body)
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
POST	/api/v2/smartFolder/getItems	Get matching items (request body)
GET	/api/v2/smartFolder/getRules	Get available rule schema

---

GET /api/v2/smartFolder/get

List all smart folders, or filter by ID.

Query Parameters

• id string (optional) — Return a single smart folder by ID

• ids string (optional) — Comma-separated smart folder IDs

Response

{
    "status": "success",
    "data": [
        {
            "id": "LRK3AQGN7VCB1",
            "name": "Large Images",
            "conditions": [
                {
                    "rules": [
                        { "property": "width", "method": ">", "value": [1920] }
                    ],
                    "match": "AND",
                    "boolean": "TRUE"
                }
            ],
            "description": "",
            "icon": "",
            "iconColor": "blue",
            "children": [],
            "modificationTime": 1700000000000,
            "imageCount": 42
        }
    ]
}

Examples

// List all smart folders
await fetch("http://localhost:41595/api/v2/smartFolder/get").then(r => r.json());

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

---

POST /api/v2/smartFolder/get

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

Examples

// 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());

---

POST /api/v2/smartFolder/create

Create a new smart folder.

Request Body

• name string (required) — Smart folder name

• conditions Object[] (required) — Filter conditions (see Conditions Format 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.

{
    "status": "success",
    "data": {
        "id": "NEW_SMART_FOLDER_ID",
        "name": "Large Images",
        "conditions": [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] }
                ],
                "match": "AND"
            }
        ],
        "description": "",
        "icon": "",
        "iconColor": "",
        "children": [],
        "modificationTime": 1700000000000,
        "imageCount": 150
    }
}

Examples

// 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());

---

POST /api/v2/smartFolder/update

Update an existing smart folder's metadata. Only the fields you include will be modified.

Request Body

• id string (required) — Smart folder ID to update

Modifiable fields:

• name string (optional) — New name

• conditions Object[] (optional) — New filter conditions

• description string (optional) — New description

• icon string (optional) — New icon

• iconColor string (optional) — New icon color

Response

Returns the updated smart folder object.

Examples

// Update name and icon color
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "Extra Large Images",
        iconColor: "green"
    })
}).then(r => r.json());

// Update filter conditions
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [3840] }
                ],
                "match": "AND"
            }
        ]
    })
}).then(r => r.json());

---

POST /api/v2/smartFolder/remove

Delete a smart folder. This also removes all its child smart folders.

Request Body

• id string (required) — Smart folder ID to delete

Response

{
    "status": "success",
    "data": true
}

Examples

await fetch("http://localhost:41595/api/v2/smartFolder/remove", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: "LRK3AQGN7VCB1" })
}).then(r => r.json());

---

GET /api/v2/smartFolder/getItems

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

Query Parameters

• smartFolderId string (required) — Smart folder ID

• orderBy string (optional) — Sort field

• fields string (optional) — Comma-separated list of fields to return

Response

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

Examples

// 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());

---

POST /api/v2/smartFolder/getItems

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

Request Body

• smartFolderId string (required) — Smart folder ID

• orderBy string (optional) — Sort field

• fields string[] (optional) — Fields to return

Examples

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());

---

GET /api/v2/smartFolder/getRules

Get the available filter rule schema. Returns supported methods, valueType, options, and more for each property, enabling callers to dynamically construct valid conditions.

Response

{
    "status": "success",
    "data": {
        "name": {
            "methods": ["contain", "uncontain", "equal", "startWith", "endWith", "empty", "not-empty", "regex"],
            "valueType": "string"
        },
        "width": {
            "methods": ["=", ">=", "<=", ">", "<", "between"],
            "valueType": "number"
        },
        "type": {
            "methods": ["equal", "unequal"],
            "valueType": "string",
            "options": ["jpg", "png", "gif", "svg", "bmp", "webp", "..."]
        }
    }
}

Examples

// Get available rules for dynamically building conditions
await fetch("http://localhost:41595/api/v2/smartFolder/getRules").then(r => r.json());

Tip: Call getRules first to get all available properties and methods, then build your conditions based on the returned schema before passing them to create or update. This helps avoid invalid filter conditions.

---

Conditions Format

A smart folder's conditions is an array of condition groups, each containing multiple rules:

[
    {
        "rules": [
            { "property": "name", "method": "contain", "value": "cat" },
            { "property": "width", "method": ">", "value": [1920] }
        ],
        "match": "AND",
        "boolean": "TRUE"
    }
]

Condition Group Properties

Property	Type	Description
rules	Object[]	Array of rules
match	string	Logic between rules. "AND": all must match; "OR": any must match
boolean	string	Include/exclude logic. "TRUE" (include, default) or "FALSE" (exclude)

Rule Properties

Property	Type	Description
property	string	Filter property (e.g., name, width, type)
method	string	Filter method (e.g., contain, >, equal)
value	any	Filter value (format depends on property and method)

Tip: Use GET /api/v2/smartFolder/getRules to query all available properties, methods, and their corresponding valueTypes.

---

SmartFolder Properties

Smart folders returned by the API contain the following properties:

Property	Type	Description
id	string	Unique smart folder ID
name	string	Name
conditions	Object[]	Filter conditions
description	string	Description
icon	string	Icon
iconColor	string	Icon color
children	Object[]	Child smart folders
modificationTime	integer	Last modification timestamp
imageCount	integer	Number of matching items