# Momentry Core API 文件總覽

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-25 |
| 文件版本 | V2.2 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V2.0 | 2026-03-22 | 創建 API 文件總覽 | Warren | OpenCode |
| V2.1 | 2026-03-24 | 新增文件分類與快速選擇指南 | OpenCode | deepseek-reasoner |
| V2.2 | 2026-03-25 | 更新 API Key 驗證說明與文件連結 | OpenCode | deepseek-reasoner |

---

## 文件架構

```
docs/
├── API_INDEX.md              ← 本文件：總覽與入口
├── API_ENDPOINTS.md          ← API 端點完整說明
├── API_EXAMPLES.md           ← 完整範例總覽（curl / n8n / WordPress）
├── API_REFERENCE.md          ← 詳細技術參考
├── DEMO_MANUAL.md            ← ⭐ 示範手冊（含 Demo API Key）
├── API_N8N_GUIDE.md          ← n8n 詳細指南
├── API_WORDPRESS_GUIDE.md     ← WordPress 詳細指南
├── API_CURL_EXAMPLES.md       ← curl 快速範例
│
├── API_TRAINING_MARCOM.md    ← ⭐ marcom 團隊教育訓練手冊
├── API_WORKFLOW_WORDPRESS_N8N.md ← WordPress/n8n 完整工作流程
└── CHUNK_DATA_STRUCTURE.md    ← Chunk 資料結構說明
```

---

## 快速選擇指南

| 需求 | 閱讀文件 |
|------|----------|
| **我要快速開始測試** | ⭐ [DEMO_MANUAL.md](./DEMO_MANUAL.md) |
| **我要查看所有範例** | [API_EXAMPLES.md](./API_EXAMPLES.md) |
| **我是 marcom 團隊** | ⭐ [API_TRAINING_MARCOM.md](./API_TRAINING_MARCOM.md) |
| 我想了解有哪些 API 端點 | [API_ENDPOINTS.md](./API_ENDPOINTS.md) |
| 我要整合 WordPress/n8n | [API_WORKFLOW_WORDPRESS_N8N.md](./API_WORKFLOW_WORDPRESS_N8N.md) |
| 我要在 n8n workflow 中呼叫 API | [DEMO_MANUAL.md](./DEMO_MANUAL.md#2-n8n-範例) |
| 我要在 WordPress 中呼叫 API | [DEMO_MANUAL.md](./DEMO_MANUAL.md#3-wordpress-範例) |
| 我要用 curl 快速測試 | [DEMO_MANUAL.md](./DEMO_MANUAL.md#1-curl-範例) |

---

## 認證

### Demo API Key

```
API Key:  muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69
Key ID:   muser_68600856036340bcafc01930eb4bd839
過期日:   2027-03-25
```

### 使用方式

```bash
curl -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  http://localhost:3002/api/v1/videos
```

---

## API URL 選擇

| 環境 | URL | 使用時機 |
|------|-----|----------|
| **本地開發** | `http://localhost:3002` | 開發/測試、繞過反向代理 |
| **外部訪問** | `https://api.momentry.ddns.net` | n8n、WordPress、遠端系統 |

### 何時用哪個

**使用 `localhost:3002`：**
- 本地終端機測試
- 當反向代理有問題時
- 快速除錯

**使用 `api.momentry.ddns.net`：**
- n8n workflow
- WordPress 網站
- 外部系統整合

---

## 常見問題

### Q: API 返回 401 錯誤？
API Key 無效或過期。請使用 Demo API Key 或建立新的 API Key。

### Q: API 返回 502 錯誤？
```bash
# 檢查服務狀態
launchctl list | grep momentry.api

# 如未啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
```

### Q: 兩個 URL 功能相同嗎？
是的，所有端點完全相同，只是訪問路徑不同。

---

## 相關文件

- [DEMO_MANUAL.md](./DEMO_MANUAL.md) - ⭐ 示範手冊（推薦新手）
- [INSTALL_MOMENTRY_API.md](./INSTALL_MOMENTRY_API.md) - API 服務安裝指南
- [PENDING_ISSUES.md](./PENDING_ISSUES.md) - 待解決問題追蹤
