diff --git a/docs/MARKBASE_API_REQUIREMENTS.md b/docs/MARKBASE_API_REQUIREMENTS.md
new file mode 100644
index 0000000..bb888f7
--- /dev/null
+++ b/docs/MARKBASE_API_REQUIREMENTS.md
@@ -0,0 +1,114 @@
+# MarkBase API 需求 - Studio 整合
+
+## 背景
+Momentry Studio 需要透過 API 管理 MarkBase 設定，但目前的 `/api/v2/config` 端點與內部 TOML 設定檔格式緊密耦合，導致：
+- 設定檔格式變更時 API 返回 500 錯誤
+- PostgreSQL→SQLite 遷移後，舊版設定檔仍要求 `postgresql` 欄位
+- Studio Settings 頁面無法正常載入/儲存設定
+
+## 需求規格
+
+### 1. 設定讀取 API
+
+**端點**: `GET /api/v2/settings`
+
+**回應範例**:
+```json
+{
+  "success": true,
+  "settings": {
+    "server": {
+      "upload_path": "/Users/accusys/momentry/var/sftpgo/data",
+      "port": 11438
+    },
+    "database": {
+      "type": "sqlite",
+      "path": "data/auth.sqlite"
+    },
+    "webdav": {
+      "enabled": true,
+      "parent_path": "/Users/accusys/momentry/var/sftpgo/data",
+      "versioning": true
+    },
+    "s3": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**需求**:
+- 回傳結構化 JSON，不依賴 TOML 格式
+- 包含所有 Studio 需要顯示的設定項目
+- 如果某個區塊不存在，回傳預設值而非錯誤
+
+### 2. 設定更新 API
+
+**端點**: `POST /api/v2/settings`
+
+**請求範例**:
+```json
+{
+  "server": {
+    "upload_path": "/new/path"
+  }
+}
+```
+
+**回應範例**:
+```json
+{
+  "success": true,
+  "message": "Settings updated"
+}
+```
+
+**需求**:
+- 支援部分更新（只傳需要修改的欄位）
+- 驗證輸入值（路徑是否存在、格式是否正確）
+- 更新後自動套用（或提示需要重啟）
+
+### 3. 設定欄位說明
+
+| 欄位 | 類型 | 說明 | Studio 使用方式 |
+|---|---|---|---|
+| `server.upload_path` | string | 上傳檔案根目錄 | Settings 頁面顯示/編輯 |
+| `server.port` | number | 服務端口 | 僅顯示 |
+| `database.type` | string | 資料庫類型 (sqlite/postgresql) | 僅顯示 |
+| `database.path` | string | SQLite 資料庫路徑 | 僅顯示 |
+| `webdav.enabled` | bool | 是否啟用 WebDAV | 僅顯示 |
+| `webdav.parent_path` | string | WebDAV 根目錄 | 僅顯示 |
+| `s3.enabled` | bool | 是否啟用 S3 | 僅顯示 |
+
+### 4. 錯誤處理
+
+**統一錯誤格式**:
+```json
+{
+  "success": false,
+  "error": "設定檔讀取失敗",
+  "details": "TOML parse error..."
+}
+```
+
+**需求**:
+- 即使設定檔有問題，也應回傳預設值而非 500 錯誤
+- 提供明確錯誤訊息供前端顯示
+
+## 當前問題
+
+| 端點 | 當前狀態 | 問題 |
+|---|---|---|
+| `GET /api/v2/config` | 500 | TOML 解析錯誤，缺少 postgresql 欄位 |
+| `POST /api/v2/config/edit` | 500 | 同上 |
+| `GET /api/v2/admin/users` | 401 | 需要 admin token 認證 |
+| `GET /api/v2/admin/shares` | 401 | 需要 admin token 認證 |
+
+## 優先順序
+
+| 優先級 | 項目 | 原因 |
+|---|---|---|
+| **P0** | `GET /api/v2/settings` | Studio Settings 頁面依賴此端點 |
+| **P0** | `POST /api/v2/settings` | 需要儲存 upload_path |
+| **P1** | Admin token 認證機制 | Users/Shares 頁面需要 |
+| **P2** | 設定驗證 API | 確保輸入值有效 |