# Folder

## 端點概覽

| 方法   | 端點                      | 說明          |
| ---- | ----------------------- | ----------- |
| GET  | `/api/v2/folder/get`    | 列出所有資料夾     |
| POST | `/api/v2/folder/get`    | 列出資料夾（請求主體） |
| POST | `/api/v2/folder/create` | 建立新資料夾      |
| POST | `/api/v2/folder/update` | 更新資料夾       |

***

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

以可選的篩選條件列出資料夾。回傳分頁結果。

### 查詢參數

* `id` string（可選）— 以 ID 回傳單一資料夾
* `ids` string（可選）— 以逗號分隔的資料夾 ID
* `isSelected` boolean（可選）— 回傳目前選取的資料夾
* `isRecent` boolean（可選）— 回傳最近使用的資料夾
* `offset` integer（可選）— 分頁偏移量，預設 `0`
* `limit` integer（可選）— 分頁限制，預設 `50`，最大 `1000`

### 回應

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

### 範例

```javascript
// 列出所有資料夾（前 50 個）
await fetch("http://localhost:41595/api/v2/folder/get").then(r => r.json());

// 以 ID 取得單一資料夾
await fetch("http://localhost:41595/api/v2/folder/get?id=LRK3AQGN7VCB1").then(r => r.json());

// 取得最近使用的資料夾
await fetch("http://localhost:41595/api/v2/folder/get?isRecent=true").then(r => r.json());
```

***

## POST /api/v2/folder/get <a href="#list-post" id="list-post"></a>

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

### 請求主體

* `id` string（可選）— 資料夾 ID
* `ids` string\[]（可選）— 資料夾 ID 陣列
* `isSelected` boolean（可選）— 目前選取的資料夾
* `isRecent` boolean（可選）— 最近使用的資料夾
* `offset` integer（可選）— 分頁偏移量，預設 `0`
* `limit` integer（可選）— 分頁限制，預設 `50`，最大 `1000`

### 範例

```javascript
// 以多個 ID 取得資料夾
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());
```

***

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

在資源庫中建立新資料夾。

### 請求主體

* `name` string（必填）— 資料夾名稱
* `description` string（可選）— 資料夾說明
* `parent` string（可選）— 父資料夾 ID。若省略則建立在根層級。

### 回應

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

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

### 範例

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

// 建立子資料夾
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());
```

***

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

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

### 請求主體

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

**可修改的欄位：**

* `name` string（可選）— 新資料夾名稱
* `description` string（可選）— 新說明
* `tags` string\[]（可選）— 替換資料夾標籤
* `iconColor` string（可選）— 資料夾圖示顏色。可選值：`red`、`orange`、`yellow`、`green`、`aqua`、`blue`、`purple`、`pink`
* `parent` string | null（可選）— 將資料夾移至新的父資料夾。設為 `null` 以移至根層級。

### 回應

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

### 範例

```javascript
// 重新命名資料夾並設定圖示顏色
await fetch("http://localhost:41595/api/v2/folder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "Renamed Folder",
        iconColor: "green"
    })
}).then(r => r.json());

// 將資料夾移至其他父資料夾
await fetch("http://localhost:41595/api/v2/folder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        parent: "NEW_PARENT_ID"
    })
}).then(r => r.json());

// 將資料夾移至根層級
await fetch("http://localhost:41595/api/v2/folder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        parent: null
    })
}).then(r => r.json());
```

***

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

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

| 屬性                 | 類型        | 說明         |
| ------------------ | --------- | ---------- |
| `id`               | string    | 唯一資料夾 ID   |
| `name`             | string    | 資料夾名稱      |
| `description`      | string    | 資料夾說明      |
| `children`         | Object\[] | 子資料夾物件陣列   |
| `modificationTime` | integer   | 最後修改時間戳記   |
| `tags`             | string\[] | 標籤名稱陣列     |
| `iconColor`        | string    | 圖示顏色名稱     |
| `imageCount`       | integer   | 此資料夾中的項目數量 |


---

# 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/zh-tw/api/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.