Introduction

Eagle Web API V2 provides a comprehensive RESTful HTTP API for interacting with the Eagle application, enabling external tools and scripts to manage your asset library programmatically.

Welcome to the Eagle Web API V2 documentation. This API allows any HTTP client — scripts, apps, browser extensions, automation tools — to interact with the Eagle application over a local HTTP server.

Looking for the V1 API? The legacy V1 API documentation is available at https://api.eagle.cool/. V2 offers a more comprehensive feature set based on the Plugin API capabilities.

Version Requirement: The V2 Web API requires Eagle 4.0 Build 21 or later.

---

Web API vs Plugin API

Eagle provides two different APIs for developers:

• Web API (this documentation) — A RESTful HTTP API for building external tools, services, scripts, or integrations that communicate with Eagle from outside the application. Use this if you are building browser extensions, automation workflows, third-party apps, or any tool that runs independently of Eagle.

• Plugin API — A JavaScript API for building plugins that run inside Eagle. Plugins have direct access to Eagle's UI, can create custom panels, respond to user interactions, and deeply integrate with the application. Use this if you want to extend Eagle's built-in functionality.

	Web API	Plugin API
Runs	Outside Eagle (any HTTP client)	Inside Eagle (as a plugin)
Protocol	HTTP REST	JavaScript API
Use case	External tools, scripts, automation	Eagle plugins, custom panels, UI extensions
Documentation	This site	developer.eagle.cool/plugin-api

---

What's New in V2

The V2 API (/api/v2/...) provides significantly more endpoints than V1 (/api/...), including:

• Full-text search with advanced query syntax (AND, OR, NOT)

• AI semantic search — search by text description or image similarity

• Tag management — create, rename, merge tags and manage tag groups

• Folder management — create, move, and organize folders

• Automatic pagination — all list endpoints are paginated by default to ensure performance

• API Playground — built-in interactive tool to test all endpoints directly in your browser

---

Prerequisites

Eagle is a local application — the API server starts automatically when the Eagle app is opened. You must have Eagle running before you can access any API endpoint.

---

Base URL

http://localhost:41595/api/v2/

The Eagle API server runs on port 41595 by default. All V2 endpoints are prefixed with /api/v2/.

---

Authentication

Local Access (localhost)

If you are making requests from the same machine where Eagle is running, no authentication is required. Requests from localhost, 127.0.0.1, or 0.0.0.0 are automatically trusted — you can start calling the API right away.

// Local access — no token needed
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

Remote Access (LAN / Network)

If you want to call the Eagle API from another device on your local network (e.g., a phone, tablet, or another computer), you must include an API Token with every request.

How to Get Your API Token

1. Open Eagle and go to Preferences (Settings)

2. Click on Developer in the left sidebar

3. Your API Token is displayed at the top of the page

4. Click the copy button next to the token to copy it to your clipboard

You can also click Regenerate Token to generate a new token at any time. Note that regenerating a token will invalidate the previous one.

Using the Token

Append the token parameter to any request URL:

// Remote access with token
const TOKEN = "f366c476-7533-4f33-b454-2bc720a1d0ea";

await fetch(`http://192.168.1.100:41595/api/v2/library/info?token=${TOKEN}`)
    .then(r => r.json());

// Also works with POST requests
await fetch(`http://192.168.1.100:41595/api/v2/item/get?token=${TOKEN}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"], limit: 20 })
}).then(r => r.json());

Keep your token private. Anyone with your API Token can access and modify your Eagle library over the network. Do not share it publicly or commit it to version control.

---

Response Format

All endpoints return responses in JSend format:

Success:

{
    "status": "success",
    "data": { ... }
}

Error:

{
    "status": "error",
    "message": "Error description"
}

---

Pagination

All list endpoints (item/get, item/query, folder/get, tag/get, etc.) return paginated results by default.

Parameter	Type	Default	Max	Description
offset	Integer	0	—	Number of items to skip
limit	Integer	50	1000	Number of items to return

Paginated response:

{
    "status": "success",
    "data": {
        "data": [ ... ],
        "total": 8500,
        "offset": 100,
        "limit": 50
    }
}

• total — Total number of matching items (before pagination)

• offset — The offset used

• limit — The limit used

• data — The paginated result array

Example: Iterating through all items

// Page 1: items 0-49
const page1 = await fetch("http://localhost:41595/api/v2/item/get?limit=50").then(r => r.json());

// Page 2: items 50-99
const page2 = await fetch("http://localhost:41595/api/v2/item/get?offset=50&limit=50").then(r => r.json());

// Continue until data.data.length < limit (last page)

---

Quick Start

// Check if Eagle is running
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());

// Get library info
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

// List first 50 items
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// Search items by tag
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tags: ["design"] })
}).then(r => r.json());

// Full-text search
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "sunset landscape" })
}).then(r => r.json());

// AI semantic search
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "an orange cat", options: { limit: 10 } })
}).then(r => r.json());

---

API Sections

Section	Description
Item	Query, add, modify, and manage items
Folder	Create, list, and organize folders
Tag	List, rename, and merge tags
Tag Group	Manage tag groups
Library	Get library metadata
App	Application information
AI Search	AI semantic & image search

---

CORS

If you are calling the Eagle API from a webpage (e.g., via a userscript manager like Tampermonkey or Violentmonkey), standard fetch requests may be blocked by the browser's Cross-Origin Resource Sharing (CORS) policy. In this case, use GM_xmlhttpRequest instead:

GM_xmlhttpRequest({
    method: "GET",
    url: "http://localhost:41595/api/v2/item/get",
    onload: function (response) {
        const data = JSON.parse(response.responseText);
        console.log(data);
    }
});

This only applies to scripts running inside web pages. If you are calling the API from Node.js, Electron, a browser extension's background script, or directly from DevTools, CORS does not apply and you can use fetch normally.

---

Rate Limits

There are no rate limits on API calls. Since the API server runs locally on your machine, all requests are processed directly without any throttling. However, keep in mind that the server's performance depends on your device's hardware — heavy operations on very large libraries may take longer to respond.