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