イントロダクション

Eagle Web API V2 は、Eagle アプリケーションと連携するための包括的な RESTful HTTP API を提供し、 外部ツールやスクリプトからアセットライブラリをプログラムで管理できるようにします。

Eagle Web API V2 ドキュメントへようこそ。この API を使用すると、スクリプト、アプリ、ブラウザ拡張機能、自動化ツールなど、あらゆる HTTP クライアントからローカル HTTP サーバーを通じて Eagle アプリケーションと連携できます。

V1 API をお探しですか？ 旧バージョンの V1 API ドキュメントは https://api.eagle.cool/ で閲覧できます。V2 は Plugin API の機能に基づき、より包括的な機能セットを提供します。

バージョン要件： V2 Web API を使用するには Eagle 4.0 Build 21 以降が必要です。

---

Web API と Plugin API

Eagle は開発者向けに 2 種類の API を提供しています：

• Web API（本ドキュメント）— Eagle アプリケーションの外部で動作するツール、サービス、スクリプト、連携ソリューションを構築するための RESTful HTTP API です。ブラウザ拡張機能、自動化ワークフロー、サードパーティアプリなど、Eagle とは独立して動作するツールの開発に適しています。

• Plugin API — Eagle の内部で動作するプラグインを構築するための JavaScript API です。プラグインは Eagle の UI に直接アクセスし、カスタムパネルの作成、ユーザー操作への応答、アプリケーションとの深い統合が可能です。Eagle の組み込み機能を拡張したい場合に適しています。

	Web API	Plugin API
実行場所	Eagle の外部（任意の HTTP クライアント）	Eagle の内部（プラグインとして）
プロトコル	HTTP REST	JavaScript API
用途	外部ツール、スクリプト、自動化	Eagle プラグイン、カスタムパネル、UI 拡張
ドキュメント	本サイト	developer.eagle.cool/plugin-api

---

V2 の新機能

V2 API（/api/v2/...）は、V1 API（/api/...）と比較して大幅に多くのエンドポイントを提供します：

• 全文検索 — 高度なクエリ構文（AND、OR、NOT）に対応

• AI セマンティック検索 — テキスト説明や画像の類似性による検索

• タグ管理 — タグの作成、名前変更、統合、タググループの管理

• フォルダ管理 — フォルダの作成、移動、整理

• 自動ページネーション — すべてのリストエンドポイントがデフォルトでページネーション対応し、パフォーマンスを確保

• API Playground — ブラウザで直接すべてのエンドポイントをテストできるインタラクティブツール

---

前提条件

Eagle はローカルアプリケーションです。API サーバーは Eagle アプリを開くと自動的に起動します。API エンドポイントにアクセスするには、Eagle が起動している必要があります。

---

ベース URL

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

Eagle API サーバーはデフォルトでポート 41595 で動作します。すべての V2 エンドポイントには /api/v2/ プレフィックスが付きます。

---

認証

ローカルアクセス（localhost）

Eagle が動作しているマシンと同じマシンからリクエストを送信する場合、認証は不要です。localhost、127.0.0.1、0.0.0.0 からのリクエストは自動的に信頼されるため、すぐに API を呼び出すことができます。

// ローカルアクセス — トークン不要
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

リモートアクセス（LAN / ネットワーク）

ローカルネットワーク上の別のデバイス（スマートフォン、タブレット、別のコンピュータなど）から Eagle API を呼び出す場合は、すべてのリクエストに API トークン を含める必要があります。

API トークンの取得方法

1. Eagle を開き、環境設定（設定）に移動します

2. 左サイドバーの デベロッパー をクリックします

3. ページ上部に API トークン が表示されます

4. トークンの横にあるコピーボタンをクリックして、クリップボードにコピーします

トークンの再生成 をクリックすると、いつでも新しいトークンを生成できます。トークンを再生成すると、以前のトークンは無効になりますのでご注意ください。

トークンの使用方法

リクエスト URL に 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());

// POST リクエストでも使用可能
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());

トークンは非公開にしてください。 API トークンを持つ人は誰でも、ネットワーク経由で Eagle ライブラリにアクセスし変更を加えることができます。トークンを公開したり、バージョン管理にコミットしないでください。

---

レスポンス形式

すべてのエンドポイントは JSend 形式でレスポンスを返します：

成功時：

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

エラー時：

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

---

ページネーション

すべてのリストエンドポイント（item/get、item/query、folder/get、tag/get など）はデフォルトでページネーションされた結果を返します。

パラメータ	型	デフォルト	最大値	説明
offset	Integer	0	--	スキップするアイテム数
limit	Integer	50	1000	返却するアイテム数

ページネーションレスポンス：

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

• total -- マッチしたアイテムの総数（ページネーション前）

• offset -- 使用されたオフセット値

• limit -- 使用されたリミット値

• data -- ページネーションされた結果の配列

例：すべてのアイテムを順に取得する

// ページ 1: アイテム 0-49
const page1 = await fetch("http://localhost:41595/api/v2/item/get?limit=50").then(r => r.json());

// ページ 2: アイテム 50-99
const page2 = await fetch("http://localhost:41595/api/v2/item/get?offset=50&limit=50").then(r => r.json());

// data.data.length < limit になるまで繰り返す（最終ページ）

---

クイックスタート

// Eagle が起動しているか確認
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());

// ライブラリ情報を取得
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());

// 最初の 50 件のアイテムを取得
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// タグでアイテムを検索
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());

// 全文検索
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 セマンティック検索
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 セクション

セクション	説明
Item	アイテムの検索、追加、変更、管理
Folder	フォルダの作成、一覧表示、整理
Tag	タグの一覧表示、名前変更、統合
Tag Group	タググループの管理
Library	ライブラリのメタデータ取得
App	アプリケーション情報
AI Search	AI セマンティック検索・画像検索

---

CORS

ウェブページから Eagle API を呼び出す場合（例：Tampermonkey や Violentmonkey などのユーザースクリプトマネージャーを使用する場合）、標準の fetch リクエストはブラウザのクロスオリジンリソース共有（CORS）ポリシーによってブロックされる可能性があります。この場合は、代わりに GM_xmlhttpRequest を使用してください：

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

これはウェブページ内で実行されるスクリプトにのみ適用されます。Node.js、Electron、ブラウザ拡張機能のバックグラウンドスクリプト、または DevTools から直接 API を呼び出す場合、CORS は適用されないため、通常通り fetch を使用できます。

---

レート制限

API 呼び出しにレート制限はありません。API サーバーはローカルマシン上で動作するため、すべてのリクエストはスロットリングなしで直接処理されます。ただし、サーバーのパフォーマンスはデバイスのハードウェアに依存するため、非常に大きなライブラリに対する負荷の高い操作はレスポンスに時間がかかる場合があります。