> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/web-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/web-api/zh-tw/api/smart-folder.md).

# Smart Folder

{% hint style="danger" %}
**此功能尚未發佈**：此 API 需要 Eagle 4.0 Build 22 或更高版本。詳細發佈時間請關注 Eagle 官網。
{% endhint %}

## 端點概覽

| 方法   | 端點                             | 說明              |
| ---- | ------------------------------ | --------------- |
| GET  | `/api/v2/smartFolder/get`      | 列出智慧型資料夾        |
| POST | `/api/v2/smartFolder/get`      | 列出智慧型資料夾（請求主體）  |
| POST | `/api/v2/smartFolder/create`   | 建立智慧型資料夾        |
| POST | `/api/v2/smartFolder/update`   | 更新智慧型資料夾        |
| POST | `/api/v2/smartFolder/remove`   | 刪除智慧型資料夾        |
| GET  | `/api/v2/smartFolder/getItems` | 取得符合條件的項目       |
| POST | `/api/v2/smartFolder/getItems` | 取得符合條件的項目（請求主體） |
| GET  | `/api/v2/smartFolder/getRules` | 取得可用規則 schema   |

***

## GET /api/v2/smartFolder/get <a href="#list" id="list"></a>

列出所有智慧型資料夾，或以 ID 篩選。

### 查詢參數

* `id` string（可選）— 以 ID 回傳單一智慧型資料夾
* `ids` string（可選）— 以逗號分隔的智慧型資料夾 ID

### 回應

```json
{
    "status": "success",
    "data": [
        {
            "id": "LRK3AQGN7VCB1",
            "name": "大尺寸圖片",
            "conditions": [
                {
                    "rules": [
                        { "property": "width", "method": ">", "value": [1920] }
                    ],
                    "match": "AND",
                    "boolean": "TRUE"
                }
            ],
            "description": "",
            "icon": "",
            "iconColor": "blue",
            "children": [],
            "modificationTime": 1700000000000,
            "imageCount": 42
        }
    ]
}
```

### 範例

```javascript
// 列出所有智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/get").then(r => r.json());

// 以 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>

與 GET 相同，但接受 JSON 主體中的篩選參數。

### 請求主體

* `id` string（可選）— 智慧型資料夾 ID
* `ids` string\[]（可選）— 智慧型資料夾 ID 陣列

### 範例

```javascript
// 以多個 ID 取得智慧型資料夾
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>

建立新的智慧型資料夾。

### 請求主體

* `name` string（必填）— 智慧型資料夾名稱
* `conditions` Object\[]（必填）— 篩選條件（格式請參考下方 [conditions 格式說明](#conditions)）
* `description` string（可選）— 說明
* `icon` string（可選）— 圖示
* `iconColor` string（可選）— 圖示顏色。可選值：`red`、`orange`、`yellow`、`green`、`aqua`、`blue`、`purple`、`pink`
* `parent` string（可選）— 父智慧型資料夾 ID。若省略則建立在根層級。

### 回應

回傳新建立的智慧型資料夾物件。

```json
{
    "status": "success",
    "data": {
        "id": "NEW_SMART_FOLDER_ID",
        "name": "大尺寸圖片",
        "conditions": [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] }
                ],
                "match": "AND"
            }
        ],
        "description": "",
        "icon": "",
        "iconColor": "",
        "children": [],
        "modificationTime": 1700000000000,
        "imageCount": 150
    }
}
```

### 範例

```javascript
// 建立篩選寬度大於 1920 的 PNG 圖片的智慧型資料夾
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "大尺寸 PNG",
        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>

更新現有智慧型資料夾的中繼資料。只有您包含的欄位會被修改。

### 請求主體

* `id` string（必填）— 要更新的智慧型資料夾 ID

**可修改的欄位：**

* `name` string（可選）— 新名稱
* `conditions` Object\[]（可選）— 新篩選條件
* `description` string（可選）— 新說明
* `icon` string（可選）— 新圖示
* `iconColor` string（可選）— 新圖示顏色

### 回應

回傳更新後的智慧型資料夾物件。

### 範例

```javascript
// 更新智慧型資料夾名稱和顏色
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "超大尺寸圖片",
        iconColor: "green"
    })
}).then(r => r.json());

// 更新篩選條件
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>

刪除智慧型資料夾。同時會刪除其所有子智慧型資料夾。

### 請求主體

* `id` string（必填）— 要刪除的智慧型資料夾 ID

### 回應

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

### 範例

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

取得符合智慧型資料夾篩選條件的項目。

### 查詢參數

* `smartFolderId` string（必填）— 智慧型資料夾 ID
* `orderBy` string（可選）— 排序欄位
* `fields` string（可選）— 以逗號分隔的回傳欄位列表

### 回應

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

### 範例

```javascript
// 取得智慧型資料夾中的所有項目
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1")
    .then(r => r.json());

// 只回傳特定欄位
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>

與 GET 相同，但接受 JSON 主體中的參數。

### 請求主體

* `smartFolderId` string（必填）— 智慧型資料夾 ID
* `orderBy` string（可選）— 排序欄位
* `fields` string\[]（可選）— 要回傳的欄位

### 範例

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

取得可用的篩選規則 schema。回傳每個 property 支援的 methods、valueType、options 等資訊，讓呼叫者可以動態建構合法的 conditions。

### 回應

```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", "..."]
        }
    }
}
```

### 範例

```javascript
// 取得可用規則，用於動態建構 conditions
await fetch("http://localhost:41595/api/v2/smartFolder/getRules").then(r => r.json());
```

{% hint style="info" %}
**使用提示：** 先呼叫 `getRules` 取得所有可用的 property 和 method，再根據回傳的 schema 建構 `conditions` 傳入 `create` 或 `update`，可避免無效的篩選條件。
{% endhint %}

***

## Conditions 格式說明 <a href="#conditions" id="conditions"></a>

智慧型資料夾的 `conditions` 是一個條件群組陣列，每個群組包含多條規則：

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

### 條件群組屬性

| 屬性        | 類型        | 說明                                        |
| --------- | --------- | ----------------------------------------- |
| `rules`   | Object\[] | 規則陣列                                      |
| `match`   | string    | 規則間的邏輯運算。`"AND"`：全部符合；`"OR"`：任一符合         |
| `boolean` | string    | 群組的包含/排除邏輯。`"TRUE"`（包含，預設）或 `"FALSE"`（排除） |

### 規則屬性

| 屬性         | 類型     | 說明                            |
| ---------- | ------ | ----------------------------- |
| `property` | string | 篩選屬性（如 `name`、`width`、`type`） |
| `method`   | string | 篩選方法（如 `contain`、`>`、`equal`） |
| `value`    | any    | 篩選值（格式依屬性和方法而定）               |

{% hint style="info" %}
**提示：** 使用 `GET /api/v2/smartFolder/getRules` 可查詢所有可用的 property、method 及其對應的 valueType。
{% endhint %}

***

## SmartFolder 屬性 <a href="#properties" id="properties"></a>

API 回傳的智慧型資料夾包含以下屬性：

| 屬性                 | 類型        | 說明          |
| ------------------ | --------- | ----------- |
| `id`               | string    | 唯一智慧型資料夾 ID |
| `name`             | string    | 名稱          |
| `conditions`       | Object\[] | 篩選條件        |
| `description`      | string    | 說明          |
| `icon`             | string    | 圖示          |
| `iconColor`        | string    | 圖示顏色        |
| `children`         | Object\[] | 子智慧型資料夾     |
| `modificationTime` | integer   | 最後修改時間戳記    |
| `imageCount`       | integer   | 符合條件的項目數量   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developer.eagle.cool/web-api/zh-tw/api/smart-folder.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.