Folder

The Folder API allows you to list, create, and manage folders in the Eagle library.

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

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

{
    "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

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

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

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

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.

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

Examples

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

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

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

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