> For the complete documentation index, see [llms.txt](https://developer.mixeder.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.mixeder.net/api-reference/readme.md).

# Mini-VPS Object Storage API Documentation

Mini-VPS のオブジェクトストレージを操作するためのREST API仕様書です。

このAPIを使用することで、アプリケーションから直接ファイルのアップロード、一覧取得、削除、アクセス制御を行うことができます。

### 🌐 基本情報 (General Info)

* Base URL: `https://mini-vps.mixeder.com/api/storage`
* 課金について:
  * ストレージ操作（アップロード、削除、一覧取得）は、ユーザーのクレジット残高を使用します。
  * クレジットが `0` 以下の場合、アップロードやAPI操作は `402 Payment Required` エラーとなります。

### 🔑 認証 (Authentication)

APIを利用するには、以下のいずれかの認証が必要です。

#### 1. APIキー認証 (推奨: 外部アプリ向け)

バケットごとに発行されたAPIキーを使用します。特定のバケットに対する操作のみが許可されます。

* Header Name: `x-api-key`
* Value: バケット設定画面で発行したAPIキー

#### 2. セッション認証 (ブラウザ・管理画面向け)

ブラウザでログイン済みの場合、セッションを利用して認証します。バケットの作成や削除など、管理者権限が必要な操作に使用します。

***

### 📂 1. ファイル操作 (File Operations)

#### 1.1 ファイル一覧取得 (List Files)

指定したバケット内のファイルとフォルダ構造を取得します。

* Endpoint: `GET /files/list`
* Auth: API Key / Session
* Use Case: ファイルマネージャーの表示、画像ギャラリーの構築。

**パラメータ (Query Parameters)**

| **パラメータ**  | **必須** | **説明**                       | **例**          |
| ---------- | ------ | ---------------------------- | -------------- |
| `bucketId` | ✅      | 対象のバケットID                    | `b1234-uuid`   |
| `prefix`   |        | 特定フォルダ内を表示する場合のパス (末尾に`/`必須) | `images/2024/` |

**cURL Request**

Bash

```bash
curl -G "https://mini-vps.mixeder.com/api/storage/files/list" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  --data-urlencode "bucketId=YOUR_BUCKET_ID" \
  --data-urlencode "prefix=photos/"
```

**Response Example**

JSON

```json
{
  "success": true,
  "currentPrefix": "photos/",
  "folders": [
    { "name": "2024", "path": "photos/2024/", "type": "folder" }
  ],
  "files": [
    { 
      "name": "vacation.jpg", 
      "path": "photos/vacation.jpg", 
      "size": 1048576, 
      "lastModified": "2024-02-07T12:00:00.000Z", 
      "type": "file" 
    }
  ]
}
```

***

#### 1.2 ファイルアップロード (Upload File)

ファイルをバケットにアップロードします。成功時、課金用ストレージ容量が加算されます。

* Endpoint: `POST /file/upload`
* Auth: API Key / Session
* Content-Type: `multipart/form-data`
* Use Case: ユーザーアイコンのアップロード、バックアップデータの保存。

**パラメータ (Form Data)**

| **パラメータ**      | **必須** | **説明**                                 |
| -------------- | ------ | -------------------------------------- |
| `file`         | ✅      | バイナリデータ (File Object)                  |
| `bucketId`     | ✅      | アップロード先のバケットID                         |
| `targetPrefix` |        | 保存先フォルダパス (例: `uploads/`)。指定しない場合はルート。 |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/file/upload" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -F "bucketId=YOUR_BUCKET_ID" \
  -F "targetPrefix=uploads/images/" \
  -F "file=@/local/path/to/image.png"
```

**Response Example**

JSON

```
{
  "success": true,
  "size": 10245000 // 更新後のバケット合計サイズ(bytes)
}
```

***

#### 1.3 ファイル削除 (Delete File)

ファイルを削除し、ストレージ容量を解放します。

* Endpoint: `POST /file/delete`
* Auth: API Key / Session
* Content-Type: `application/json`

**パラメータ (JSON Body)**

| **パラメータ**  | **必須** | **説明**                                      |
| ---------- | ------ | ------------------------------------------- |
| `bucketId` | ✅      | バケットID                                      |
| `key`      | ✅      | 削除するファイルのパス (例: `uploads/images/image.png`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/file/delete" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "key": "uploads/images/image.png"
  }'
```

***

### 📁 2. フォルダ操作 (Folder Operations)

#### 2.1 フォルダ作成 (Create Folder)

空のフォルダ（プレフィックス）を作成します。

※ オブジェクトストレージの仕様上、0バイトのオブジェクトとして作成されます。

* Endpoint: `POST /folder/create`
* Auth: API Key / Session

**パラメータ (JSON Body)**

| **パラメータ**       | **必須** | **説明**                       |
| --------------- | ------ | ---------------------------- |
| `bucketId`      | ✅      | バケットID                       |
| `folderName`    | ✅      | 作成するフォルダ名 (例: `new_docs`)    |
| `currentPrefix` |        | 親フォルダがある場合 (例: `project_a/`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/folder/create" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "folderName": "logs",
    "currentPrefix": "server_a/"
  }'
# 結果: "server_a/logs/" が作成されます
```

***

#### 2.2 フォルダ一括削除 (Delete Folder)

指定したフォルダと、その中にあるすべてのファイルを再帰的に削除します。

※ 削除されたファイル分の容量がクレジット計算から減算されます。取り消しできません。

* Endpoint: `POST /folder/delete`
* Auth: API Key / Session

**パラメータ (JSON Body)**

| **パラメータ**    | **必須** | **説明**                            |
| ------------ | ------ | --------------------------------- |
| `bucketId`   | ✅      | バケットID                            |
| `folderPath` | ✅      | 削除対象のフォルダパス (例: `server_a/logs/`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/folder/delete" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "folderPath": "server_a/logs/"
  }'
```

***

### 🔗 3. アクセス共有 (Access Control)

#### 3.1 署名付きURL発行 (Generate Signed URL)

プライベートなファイルに対して、一定時間だけアクセス可能なURLを発行します。

* Endpoint: `POST /url/sign`
* Auth: API Key / Session
* Use Case: チャットでのファイル共有、期限付きダウンロードリンク。

**パラメータ (JSON Body)**

| **パラメータ**  | **必須** | **説明**    |
| ---------- | ------ | --------- |
| `bucketId` | ✅      | バケットID    |
| `key`      | ✅      | 対象ファイルのパス |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/url/sign" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "key": "private/contract.pdf"
  }'
```

**Response Example**

JSON

```
{
  "success": true,
  "url": "/s/my-bucket/private/contract.pdf?expires=1738999999&signature=a1b2c3d4..."
}
```

※ ブラウザでこのURLにアクセスするとファイルが表示・ダウンロードされます。

***

### ⚙️ 4. 管理・設定 (Management)

これらのAPIは通常、APIキーではなく\*\*セッション認証（管理画面）\*\*から呼び出されます。

#### 4.1 バケット作成 (Create Bucket)

* Endpoint: `POST /create`
* Auth: Session Only (Cookie)
* Body: `{ "bucketName": "unique-name" }`

#### 4.2 バケット削除 (Delete Bucket)

バケットごと全データを削除します。

* Endpoint: `POST /delete`
* Auth: Session Only (Cookie)
* Body: `{ "bucketId": "..." }`

#### 4.3 容量同期 (Sync Stats)

データベース上の容量表示と、実際のクラウドストレージ上の容量にズレが生じた場合に実行し、正しい値に修正します。

* Endpoint: `POST /sync`
* Auth: API Key / Session
* Body: `{ "bucketId": "..." }`

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/sync" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "bucketId": "YOUR_BUCKET_ID" }'
```

***

#### 4.4 APIキー管理

* 作成: `POST /apikey/create` - Body: `{ "bucketId": "..." }`
* 削除: `POST /apikey/delete` - Body: `{ "bucketId": "...", "apiKey": "..." }`

***

### 🚨 エラーコード一覧 (Error Codes)

APIはHTTPステータスコードで成否を返します。レスポンスボディには `{ "error": "詳細メッセージ" }` が含まれます。

| **Status** | **Code** | **説明**           | **対処法**                       |
| ---------- | -------- | ---------------- | ----------------------------- |
| ✅          | 200      | OK               | リクエスト成功。                      |
| ❌          | 400      | Bad Request      | パラメータ不足、またはファイルサイズ制限超過。       |
| ❌          | 401      | Unauthorized     | ログインしていない、またはセッション切れ。         |
| ❌          | 402      | Payment Required | クレジット残高不足。チャージしてください。         |
| ❌          | 403      | Forbidden        | APIキーが無効、または対象バケットへの権限がありません。 |
| ❌          | 404      | Not Found        | 指定されたバケットIDやファイルが存在しません。      |
| ❌          | 500      | Server Error     | サーバー内部エラー。管理者へ連絡してください。       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.mixeder.net/api-reference/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.