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


---

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