Item

Item API を使用すると、Eagle ライブラリ内のアイテムの検索、追加、変更、管理を行うことができます。

エンドポイント一覧

メソッド	エンドポイント	説明
GET	/api/v2/item/get	フィルタ付きでアイテムを一覧表示
POST	/api/v2/item/get	フィルタ付きでアイテムを一覧表示（ボディ）
POST	/api/v2/item/query	全文検索
GET	/api/v2/item/countAll	全アイテム数を取得
POST	/api/v2/item/add	新しいアイテムを追加
POST	/api/v2/item/update	アイテムを更新
POST	/api/v2/item/setCustomThumbnail	カスタムサムネイルを設定
POST	/api/v2/item/refreshThumbnail	サムネイルを再生成

---

GET /api/v2/item/get

オプションのフィルタを使用してアイテムを一覧表示します。ページネーションされた結果を返します。

クエリパラメータ

• id string（任意）-- ID でアイテムを1件取得

• ids string（任意）-- カンマ区切りのアイテム ID

• isSelected boolean（任意）-- 現在選択中のアイテムを返却

• isUntagged boolean（任意）-- タグなしのアイテムを返却

• isUnfiled boolean（任意）-- フォルダに未分類のアイテムを返却

• keywords string（任意）-- キーワードでフィルタ（カンマ区切り）

• tags string（任意）-- タグでフィルタ（カンマ区切り）

• folders string（任意）-- フォルダ ID でフィルタ（カンマ区切り）

• ext string（任意）-- ファイル拡張子でフィルタ（例：jpg、png）

• annotation string（任意）-- 注釈テキストでフィルタ

• rating integer（任意）-- 評価でフィルタ（0--5）

• url string（任意）-- ソース URL でフィルタ

• shape string（任意）-- 形状でフィルタ：square、portrait、panoramic-portrait、landscape、panoramic-landscape

• fields string（任意）-- 返却するフィールドのカンマ区切りリスト（パフォーマンス向上に有効）

• offset integer（任意）-- ページネーションオフセット、デフォルト 0

• limit integer（任意）-- ページネーションリミット、デフォルト 50、最大 1000

レスポンス

{
    "status": "success",
    "data": {
        "data": [
            {
                "id": "M3QSGJNQTC2DG",
                "name": "sunset-photo",
                "ext": "jpg",
                "width": 1920,
                "height": 1080,
                "url": "https://example.com/photo.jpg",
                "tags": ["nature", "sunset"],
                "folders": ["FOLDER_ID_1"],
                "star": 4,
                "annotation": "Beautiful sunset at the beach",
                "modificationTime": 1700000000000
            }
        ],
        "total": 1250,
        "offset": 0,
        "limit": 50
    }
}

例

// 最初の 50 件を一覧表示（デフォルト）
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// ID でアイテムを1件取得
await fetch("http://localhost:41595/api/v2/item/get?id=M3QSGJNQTC2DG").then(r => r.json());

// 拡張子でフィルタしてページネーション
await fetch("http://localhost:41595/api/v2/item/get?ext=png&offset=0&limit=100").then(r => r.json());

// パフォーマンス向上のため特定フィールドのみ返却
await fetch("http://localhost:41595/api/v2/item/get?fields=id,name,tags").then(r => r.json());

---

POST /api/v2/item/get

GET と同じですが、フィルタパラメータを JSON ボディで受け付けます。配列を含む複雑なクエリに便利です。

リクエストボディ

• id string（任意）-- アイテム ID

• ids string[]（任意）-- アイテム ID の配列

• isSelected boolean（任意）-- 現在選択中のアイテム

• isUntagged boolean（任意）-- タグなしのアイテム

• isUnfiled boolean（任意）-- フォルダに未分類のアイテム

• keywords string[]（任意）-- マッチするキーワード

• tags string[]（任意）-- マッチするタグ

• folders string[]（任意）-- マッチするフォルダ ID

• ext string（任意）-- ファイル拡張子

• annotation string（任意）-- 注釈テキスト

• rating integer（任意）-- 評価（0--5）

• url string（任意）-- ソース URL

• shape string（任意）-- 画像の形状

• fields string[]（任意）-- 返却するフィールド

• offset integer（任意）-- ページネーションオフセット、デフォルト 0

• limit integer（任意）-- ページネーションリミット、デフォルト 50、最大 1000

例

// タグでフィルタ
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        tags: ["design", "inspiration"],
        limit: 20
    })
}).then(r => r.json());

// 複数の ID でアイテムを取得
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"]
    })
}).then(r => r.json());

// 特定フォルダ内の JPG ファイルをフィルタし、id と name のみ返却
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ext: "jpg",
        folders: ["FOLDER_ID"],
        fields: ["id", "name", "tags"],
        offset: 0,
        limit: 100
    })
}).then(r => r.json());

パフォーマンスのヒント： fields パラメータを使用して、必要なデータのみを返却してください。大規模なライブラリを扱う際のレスポンスタイムが大幅に改善されます。

---

POST /api/v2/item/query

アイテム名、タグ、注釈、URL、フォルダ名などに対する全文検索を実行します。高度なクエリ構文に対応しています。ページネーションされた結果を返します。

リクエストボディ

• query string -- 検索クエリ文字列

• offset integer（任意）-- ページネーションオフセット、デフォルト 0

• limit integer（任意）-- ページネーションリミット、デフォルト 50、最大 1000

クエリ構文

構文	説明	例
word	単語を含む必要がある	cat
a b	両方を含む（AND）	cat dog
a OR b	いずれかを含む（OR）	cat OR dog
a || b	いずれかを含む（OR）	cat || dog
-word	含まない（NOT）	cat -dog
"phrase"	完全一致フレーズ	"orange cat"
(a OR b) c	グループ化	(cat OR dog) cute

例

// シンプルな検索
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "sunset" })
}).then(r => r.json());

// 高度な検索: "cat" または "dog" を含むが "cartoon" を含まないアイテム
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        query: "(cat OR dog) -cartoon",
        limit: 20
    })
}).then(r => r.json());

// 検索結果をページネーションで取得
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "design", offset: 50, limit: 50 })
}).then(r => r.json());

---

GET /api/v2/item/countAll

ライブラリ内のアイテムの総数を返します。

レスポンス

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

例

await fetch("http://localhost:41595/api/v2/item/countAll").then(r => r.json());

---

POST /api/v2/item/add

Eagle に新しいアイテムを追加します。URL、Base64 データ、ローカルファイルパス、またはブックマークからの追加に対応しています。

リクエストボディ

• id string（任意）-- カスタムアイテム ID

• name string（任意）-- アイテム名

• tags string[]（任意）-- 割り当てるタグ

• folders string[]（任意）-- アイテムを追加するフォルダ ID

• annotation string（任意）-- アイテムの注釈

• website string（任意）-- ソースウェブサイトの URL

さらに以下のいずれか1つ：

• url string -- ダウンロードする画像の URL

• base64 string -- Base64 エンコードされた画像データ

• path string -- インポートするローカルファイルパス

• bookmarkURL string -- ブックマークとして追加する URL

例

// URL から追加
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://example.com/photo.jpg",
        name: "Example Photo",
        tags: ["downloaded", "example"],
        folders: ["FOLDER_ID"]
    })
}).then(r => r.json());

// ローカルファイルパスから追加
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        path: "C:\\Users\\User\\Downloads\\design.png",
        name: "My Design",
        tags: ["design"]
    })
}).then(r => r.json());

// ブックマークを追加
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        bookmarkURL: "https://www.example.com",
        name: "Example Site",
        tags: ["bookmark"]
    })
}).then(r => r.json());

// 一括で複数のアイテムを追加（最大 1000 件）
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        items: [
            { url: "https://example.com/photo1.jpg", name: "Photo 1" },
            { path: "C:\\Users\\User\\Downloads\\design.png", name: "Design" },
            { bookmarkURL: "https://www.example.com", name: "Bookmark" }
        ]
    })
}).then(r => r.json());

バッチモード

items 配列を渡すことで、一度に複数のアイテムを追加できます（最大 1000 件）。配列内の各オブジェクトは単一モードと同じ形式で、path、url、bookmarkURL、base64 を混在させることができます。

レスポンス

単一モードでは新しいアイテムの ID を返します：

{
    "status": "success",
    "data": { "id": "M3QSGJNQTC2DG" }
}

バッチモードではすべての新しいアイテムの ID を返します：

{
    "status": "success",
    "data": { "ids": ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"] }
}

---

POST /api/v2/item/update

既存アイテムのメタデータを更新します。指定したフィールドのみが変更されます。

リクエストボディ

• id string（必須）-- 更新するアイテムの ID

変更可能なフィールド：

• name string（任意）-- 新しい名前

• tags string[]（任意）-- タグを置換

• folders string[]（任意）-- フォルダの割り当てを置換

• annotation string（任意）-- 新しい注釈

• url string（任意）-- 新しいソース URL

• star integer（任意）-- 評価、0--5

• modificationTime integer（任意）-- 変更タイムスタンプ

• noThumbnail boolean（任意）-- サムネイルなしとしてマーク

• noPreview boolean（任意）-- プレビュー不可としてマーク

• isDeleted boolean（任意）-- ゴミ箱への移動 / ゴミ箱からの復元

レスポンス

更新されたアイテムオブジェクトを返します。

例

// アイテム名とタグを更新
await fetch("http://localhost:41595/api/v2/item/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        name: "Updated Name",
        tags: ["tag1", "tag2"],
        star: 5
    })
}).then(r => r.json());

// アイテムをゴミ箱に移動
await fetch("http://localhost:41595/api/v2/item/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        isDeleted: true
    })
}).then(r => r.json());

---

POST /api/v2/item/setCustomThumbnail

ローカルの画像ファイルからアイテムのカスタムサムネイルを設定します。

リクエストボディ

• itemId string（必須）-- アイテムの ID

• filePath string（必須）-- サムネイル画像のパス

例

await fetch("http://localhost:41595/api/v2/item/setCustomThumbnail", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        itemId: "M3QSGJNQTC2DG",
        filePath: "C:\\Users\\User\\thumbnails\\custom.png"
    })
}).then(r => r.json());

この操作は非同期です。API はサムネイルが生成されるまで最大 10 秒間待機してからレスポンスを返します。

---

POST /api/v2/item/refreshThumbnail

アイテムのサムネイルを再生成し、ファイルサイズ、寸法、カラーパレットを更新します。

リクエストボディ

• itemId string（必須）-- アイテムの ID

例

await fetch("http://localhost:41595/api/v2/item/refreshThumbnail", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ itemId: "M3QSGJNQTC2DG" })
}).then(r => r.json());

---

アイテムのプロパティ

API から返されるアイテムには以下のプロパティが含まれます：

プロパティ	型	説明
id	string	一意のアイテム ID
name	string	アイテム名
ext	string	ファイル拡張子
width	integer	画像の幅（ピクセル）
height	integer	画像の高さ（ピクセル）
url	string	ソース URL
isDeleted	boolean	ゴミ箱にあるかどうか
annotation	string	アイテムの注釈/メモ
tags	string[]	タグ名の配列
folders	string[]	フォルダ ID の配列
palettes	Object[]	カラーパレット情報
size	integer	ファイルサイズ（バイト）
star	integer	評価（0--5）
modificationTime	integer	最終変更タイムスタンプ
noThumbnail	boolean	サムネイルがないかどうか
noPreview	boolean	ダブルクリックプレビューが無効かどうか