> 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/api/folder.md).

# Folder

## エンドポイント一覧

| メソッド | エンドポイント                 | 説明             |
| ---- | ----------------------- | -------------- |
| GET  | `/api/v2/folder/get`    | 全フォルダを一覧表示     |
| POST | `/api/v2/folder/get`    | フォルダを一覧表示（ボディ） |
| POST | `/api/v2/folder/create` | 新しいフォルダを作成     |
| POST | `/api/v2/folder/update` | フォルダを更新        |

***

## GET /api/v2/folder/get <a href="#list" id="list"></a>

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

### クエリパラメータ

* `id` string（任意）-- ID でフォルダを1件取得
* `ids` string（任意）-- カンマ区切りのフォルダ ID
* `isSelected` boolean（任意）-- 現在選択中のフォルダを返却
* `isRecent` boolean（任意）-- 最近使用したフォルダを返却
* `offset` integer（任意）-- ページネーションオフセット、デフォルト `0`
* `limit` integer（任意）-- ページネーションリミット、デフォルト `50`、最大 `1000`

### レスポンス

```json
{
    "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
    }
}
```

### 例

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

// ID でフォルダを1件取得
await fetch("http://localhost:41595/api/v2/folder/get?id=LRK3AQGN7VCB1").then(r => r.json());

// 最近使用したフォルダを取得
await fetch("http://localhost:41595/api/v2/folder/get?isRecent=true").then(r => r.json());
```

***

## POST /api/v2/folder/get <a href="#list-post" id="list-post"></a>

GET と同じですが、フィルタパラメータを JSON ボディで受け付けます。

### リクエストボディ

* `id` string（任意）-- フォルダ ID
* `ids` string\[]（任意）-- フォルダ ID の配列
* `isSelected` boolean（任意）-- 現在選択中のフォルダ
* `isRecent` boolean（任意）-- 最近使用したフォルダ
* `offset` integer（任意）-- ページネーションオフセット、デフォルト `0`
* `limit` integer（任意）-- ページネーションリミット、デフォルト `50`、最大 `1000`

### 例

```javascript
// 複数の ID でフォルダを取得
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 <a href="#create" id="create"></a>

ライブラリに新しいフォルダを作成します。

### リクエストボディ

* `name` string（必須）-- フォルダ名
* `description` string（任意）-- フォルダの説明
* `parent` string（任意）-- 親フォルダの ID。省略した場合はルートレベルに作成されます。

### レスポンス

新しく作成されたフォルダオブジェクトを返します。

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

### 例

```javascript
// ルートレベルにフォルダを作成
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());

// サブフォルダを作成
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 <a href="#update" id="update"></a>

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

### リクエストボディ

* `id` string（必須）-- 更新するフォルダの ID

**変更可能なフィールド：**

* `name` string（任意）-- 新しいフォルダ名
* `description` string（任意）-- 新しい説明
* `tags` string\[]（任意）-- フォルダのタグを置換
* `iconColor` string（任意）-- フォルダのアイコン色。以下のいずれか：`red`、`orange`、`yellow`、`green`、`aqua`、`blue`、`purple`、`pink`
* `parent` string | null（任意）-- フォルダを別の親に移動。`null` に設定するとルートに移動します。

### レスポンス

更新されたフォルダオブジェクトを返します。

### 例

```javascript
// フォルダ名を変更してアイコン色を設定
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());

// フォルダを別の親に移動
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());

// フォルダをルートレベルに移動
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());
```

***

## フォルダのプロパティ <a href="#properties" id="properties"></a>

API から返されるフォルダには以下のプロパティが含まれます：

| プロパティ              | 型         | 説明             |
| ------------------ | --------- | -------------- |
| `id`               | string    | 一意のフォルダ ID     |
| `name`             | string    | フォルダ名          |
| `description`      | string    | フォルダの説明        |
| `children`         | Object\[] | 子フォルダオブジェクトの配列 |
| `modificationTime` | integer   | 最終変更タイムスタンプ    |
| `tags`             | string\[] | タグ名の配列         |
| `iconColor`        | string    | アイコンの色名        |
| `imageCount`       | integer   | このフォルダ内のアイテム数  |