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

# Folder

## Endpoints Overview

| Method | Endpoint                | Description         |
| ------ | ----------------------- | ------------------- |
| GET    | `/api/v2/folder/get`    | List all folders    |
| POST   | `/api/v2/folder/get`    | List folders (body) |
| POST   | `/api/v2/folder/create` | Create a new folder |
| POST   | `/api/v2/folder/update` | Update a folder     |

***

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

List folders with optional filtering. Returns paginated results.

### Query Parameters

* `id` string (optional) — Return a single folder by ID
* `ids` string (optional) — Comma-separated folder IDs
* `isSelected` boolean (optional) — Return the currently selected folder
* `isRecent` boolean (optional) — Return recently used folders
* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Response

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

### Examples

```javascript
// List all folders (first 50)
await fetch("http://localhost:41595/api/v2/folder/get").then(r => r.json());

// Get a single folder by ID
await fetch("http://localhost:41595/api/v2/folder/get?id=LRK3AQGN7VCB1").then(r => r.json());

// Get recently used folders
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>

Same as GET, but accepts filter parameters in the JSON body.

### Request Body

* `id` string (optional) — Folder ID
* `ids` string\[] (optional) — Array of folder IDs
* `isSelected` boolean (optional) — Currently selected folder
* `isRecent` boolean (optional) — Recently used folders
* `offset` integer (optional) — Pagination offset, default `0`
* `limit` integer (optional) — Pagination limit, default `50`, max `1000`

### Example

```javascript
// Get folders by multiple IDs
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>

Create a new folder in the library.

### Request Body

* `name` string (required) — Folder name
* `description` string (optional) — Folder description
* `parent` string (optional) — Parent folder ID. If omitted, creates at root level.

### Response

Returns the newly created folder object.

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

### Examples

```javascript
// Create a root-level folder
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());

// Create a subfolder
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>

Update an existing folder's metadata. Only the fields you include will be modified.

### Request Body

* `id` string (required) — The folder ID to update

**Modifiable fields:**

* `name` string (optional) — New folder name
* `description` string (optional) — New description
* `tags` string\[] (optional) — Replace folder tags
* `iconColor` string (optional) — Folder icon color. One of: `red`, `orange`, `yellow`, `green`, `aqua`, `blue`, `purple`, `pink`
* `parent` string | null (optional) — Move folder to a new parent. Set to `null` to move to root.

### Response

Returns the updated folder object.

### Examples

```javascript
// Rename a folder and set icon color
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());

// Move folder to a different parent
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());

// Move folder to root level
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 Properties <a href="#properties" id="properties"></a>

Folders returned by the API contain the following properties:

| Property           | Type      | Description                    |
| ------------------ | --------- | ------------------------------ |
| `id`               | string    | Unique folder ID               |
| `name`             | string    | Folder name                    |
| `description`      | string    | Folder description             |
| `children`         | Object\[] | Array of child folder objects  |
| `modificationTime` | integer   | Last modification timestamp    |
| `tags`             | string\[] | Array of tag names             |
| `iconColor`        | string    | Icon color name                |
| `imageCount`       | integer   | Number of items in this folder |