# Smart Folder

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

## 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 <a href="#list" id="list"></a>

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

```json
{
    "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

```javascript
// 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 <a href="#list-post" id="list-post"></a>

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

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

***

## POST /api/v2/smartFolder/create <a href="#create" id="create"></a>

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.

```json
{
    "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

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

***

## POST /api/v2/smartFolder/update <a href="#update" id="update"></a>

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

```javascript
// 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 <a href="#remove" id="remove"></a>

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

### Request Body

* `id` string (required) — Smart folder ID to delete

### Response

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

### Examples

```javascript
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 <a href="#get-items" id="get-items"></a>

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

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

### Examples

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

***

## POST /api/v2/smartFolder/getItems <a href="#get-items-post" id="get-items-post"></a>

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

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

***

## GET /api/v2/smartFolder/getRules <a href="#get-rules" id="get-rules"></a>

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

### Response

```json
{
    "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

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

{% hint style="info" %}
**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.
{% endhint %}

***

## Conditions Format <a href="#conditions" id="conditions"></a>

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

```json
[
    {
        "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) |

{% hint style="info" %}
**Tip:** Use `GET /api/v2/smartFolder/getRules` to query all available properties, methods, and their corresponding valueTypes.
{% endhint %}

***

## SmartFolder Properties <a href="#properties" id="properties"></a>

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    |


---

# 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/api/smart-folder.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.