> 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/folder.md).

# 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   | 此資料夾中的項目數量 |