> 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/ja-jp/get-started/readme.md).

# イントロダクション

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

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

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

{% hint style="warning" %}
**バージョン要件：** V2 Web API を使用するには **Eagle 4.0 Build 21** 以降が必要です。
{% endhint %}

***

## Web API と Plugin API <a href="#web-api-vs-plugin-api" id="web-api-vs-plugin-api"></a>

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

* **Web API**（本ドキュメント）— Eagle アプリケーションの**外部**で動作するツール、サービス、スクリプト、連携ソリューションを構築するための RESTful HTTP API です。ブラウザ拡張機能、自動化ワークフロー、サードパーティアプリなど、Eagle とは独立して動作するツールの開発に適しています。
* [**Plugin API**](https://developer.eagle.cool/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](https://developer.eagle.cool/plugin-api) |

***

## V2 の新機能 <a href="#whats-new" id="whats-new"></a>

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

* **全文検索** — 高度なクエリ構文（AND、OR、NOT）に対応
* **AI セマンティック検索** — テキスト説明や画像の類似性による検索
* **タグ管理** — タグの作成、名前変更、統合、タググループの管理
* **フォルダ管理** — フォルダの作成、移動、整理
* **自動ページネーション** — すべてのリストエンドポイントがデフォルトでページネーション対応し、パフォーマンスを確保
* [**API Playground**](/web-api/ja-jp/get-started/playground.md) — ブラウザで直接すべてのエンドポイントをテストできるインタラクティブツール

***

## 前提条件 <a href="#prerequisites" id="prerequisites"></a>

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

***

## ベース URL <a href="#base-url" id="base-url"></a>

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

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

***

## 認証 <a href="#authentication" id="authentication"></a>

### ローカルアクセス（localhost）

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

```javascript
// ローカルアクセス — トークン不要
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` パラメータを追加します：

```javascript
// トークンを使用したリモートアクセス
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());
```

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

***

## レスポンス形式 <a href="#response-format" id="response-format"></a>

すべてのエンドポイントは [JSend](https://github.com/omniti-labs/jsend) 形式でレスポンスを返します：

**成功時：**

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

**エラー時：**

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

***

## ページネーション <a href="#pagination" id="pagination"></a>

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

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

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

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

* `total` -- マッチしたアイテムの総数（ページネーション前）
* `offset` -- 使用されたオフセット値
* `limit` -- 使用されたリミット値
* `data` -- ページネーションされた結果の配列

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

```javascript
// ページ 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 になるまで繰り返す（最終ページ）
```

***

## クイックスタート <a href="#quick-start" id="quick-start"></a>

```javascript
// 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 セクション <a href="#api-sections" id="api-sections"></a>

| セクション                                        | 説明                |
| -------------------------------------------- | ----------------- |
| [Item](/web-api/ja-jp/api/item.md)           | アイテムの検索、追加、変更、管理  |
| [Folder](/web-api/ja-jp/api/folder.md)       | フォルダの作成、一覧表示、整理   |
| [Tag](/web-api/ja-jp/api/tag.md)             | タグの一覧表示、名前変更、統合   |
| [Tag Group](/web-api/ja-jp/api/tag-group.md) | タググループの管理         |
| [Library](/web-api/ja-jp/api/library.md)     | ライブラリのメタデータ取得     |
| [App](/web-api/ja-jp/api/app.md)             | アプリケーション情報        |
| [AI Search](/web-api/ja-jp/api/ai-search.md) | AI セマンティック検索・画像検索 |

***

## CORS <a href="#cors" id="cors"></a>

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

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

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

***

## レート制限 <a href="#rate-limits" id="rate-limits"></a>

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