---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core Dev API 參考文件"
date: "2026-05-06"
version: "V1.1"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "api"
  - "reference"
  - "dev"
  - "v1.1"
  - "restful"
related_documents:
  - "MOMENTRY_CORE_API_V1.0.0.md"
  - "RELEASE/RELEASE_API_REFERENCE_v1.0.0.md"
---

# Momentry Core Dev API 參考文件

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-05-06 |
| 文件版本 | V1.1 |
| Base URL | `http://localhost:3003` |
| 認證方式 | Header `X-API-Key`（部分端點需要） |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.1 | 2026-05-06 | 從程式碼實際路由重新產生 53 端點清單 | OpenCode |
| V1.0 | 2026-04-30 | 原始文件，含多個不存在之端點 | OpenCode |

---

## 認證

- **Header**: `X-API-Key: <your_api_key>`
- 目前 `/api/v1/auth/login` 回傳固定 demo Key: `muser_test_001`
- Protected routes 透過 `api_key_validation` middleware 驗證
- Public routes（免 Key）: `/health`, `/health/detailed`, `/api/v1/auth/login`

---

## 端點列表

總計 **53 個註冊路由**（另有 1 個定義但未掛載）。

### 1. 系統與認證（System & Auth）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 1 | GET | `/health` | 基本健康檢查（回傳 status/version/uptime） | ❌ |
| 2 | GET | `/health/detailed` | 詳細健康狀態（含 PG/Redis/Qdrant/MongoDB 各別延遲） | ❌ |
| 3 | POST | `/api/v1/auth/login` | 登入（固定 demo/demo，回傳 API Key） | ❌ |
| 4 | POST | `/api/v1/auth/logout` | 登出 | ✅ |

### 2. 檔案管理（File Management）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 5 | GET | `/api/v1/files` | 檔案列表（支援分頁、status、q、uuid 過濾） | ✅ |
| 6 | GET | `/api/v1/file/:file_uuid` | 檔案詳細資訊（含 probe_json、metadata） | ✅ |
| 7 | POST | `/api/v1/files/register` | 從磁碟註冊新檔案（支援 pattern 批次註冊） | ✅ |
| 8 | POST | `/api/v1/unregister` | 取消註冊檔案 | ✅ |
| 9 | GET | `/api/v1/files/scan` | 掃描 SFTPGo demo 目錄中的新檔案 | ✅ |
| 10 | GET | `/api/v1/file/:file_uuid/probe` | 取得/快取 ffprobe 資訊 | ✅ |
| 11 | POST | `/api/v1/file/:file_uuid/process` | 啟動處理 pipeline（建立 monitor job） | ✅ |
| 12 | GET | `/api/v1/file/:file_uuid/chunks` | 列出 pre_chunks | ✅ |
| 13 | GET | `/api/v1/progress/:uuid` | 即時處理進度（來自 Redis PubSub） | ✅ |
| 14 | GET | `/api/v1/jobs` | 任務列表（支援分頁、status 過濾） | ✅ |

### 3. 搜尋（Search）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 15 | POST | `/api/v1/search/visual` | 視覺搜尋 | ✅ |
| 16 | POST | `/api/v1/search/visual/class` | 依物件類別過濾搜尋 | ✅ |
| 17 | POST | `/api/v1/search/visual/density` | 依視覺密度搜尋 | ✅ |
| 18 | POST | `/api/v1/search/visual/stats` | 視覺統計資料 | ✅ |
| 19 | POST | `/api/v1/search/visual/combination` | 視覺組合搜尋（多條件） | ✅ |
| 20 | POST | `/api/v1/search/smart` | 智慧搜尋（語意向量） | ✅ |
| 21 | POST | `/api/v1/search/universal` | 通用搜尋 | ✅ |
| 22 | POST | `/api/v1/search/frames` | 影格搜尋 | ✅ |

### 4. 身份管理（Identity）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 23 | GET | `/api/v1/identities` | 身份列表 | ✅ |
| 24 | POST | `/api/v1/identity` | 建立身份（從 face.json 建立參考向量） | ✅ |
| 25 | GET | `/api/v1/identity/:identity_uuid` | 身份詳細資訊 | ✅ |
| 26 | DELETE | `/api/v1/identity/:identity_uuid` | 刪除身份 | ✅ |
| 27 | GET | `/api/v1/identity/:identity_uuid/files` | 該身份出現的所有檔案 | ✅ |
| 28 | GET | `/api/v1/identity/:identity_uuid/chunks` | 該身份的時間軸片段 | ✅ |
| 29 | POST | `/api/v1/identity/:identity_uuid/bind` | 綁定信號至身份 | ✅ |
| 30 | POST | `/api/v1/identity/:identity_uuid/unbind` | 解除綁定 | ✅ |
| 31 | POST | `/api/v1/identity/:from_uuid/mergeinto` | 合併身份（將 from 合併至目標） | ✅ |

### 5. 臉部（Face）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 32 | GET | `/api/v1/faces/candidates` | 臉部候選列表（未綁定者） | ✅ |

### 6. 媒體串流（Media）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 33 | GET | `/api/v1/file/:file_uuid/video` | 影片串流 | ✅ |
| 34 | GET | `/api/v1/file/:file_uuid/video/bbox` | 含 Bounding Box 的影片串流 | ✅ |
| 35 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | 特定 trace 的影片片段 | ✅ |
| 36 | GET | `/api/v1/file/:file_uuid/thumbnail` | 影片縮圖 | ✅ |

### 7. 檔案身份關聯（File-Identity）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 37 | GET | `/api/v1/file/:file_uuid/identities` | 該檔案的所有關聯身份 | ✅ |

### 8. Agent

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 38 | POST | `/api/v1/agents/translate` | 翻譯 Agent | ✅ |
| 39 | POST | `/api/v1/agents/identity/analyze` | 身份分析 Agent | ✅ |
| 40 | POST | `/api/v1/agents/identity/suggest` | 身份合併建議 | ✅ |
| 41 | GET | `/api/v1/agents/identity/status` | 身份 Agent 狀態 | ✅ |
| 42 | POST | `/api/v1/agents/suggest/clustering` | 聚類建議 | ✅ |
| 43 | POST | `/api/v1/agents/suggest/merge` | 合併建議 | ✅ |
| 44 | POST | `/api/v1/agents/5w1h/analyze` | 5W1H 分析 | ✅ |
| 45 | POST | `/api/v1/agents/5w1h/batch` | 5W1H 批量分析 | ✅ |
| 46 | GET | `/api/v1/agents/5w1h/status` | 5W1H 狀態 | ✅ |

### 9. 資源管理（Resource）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 47 | POST | `/api/v1/resource/register` | 註冊運算資源 | ✅ |
| 48 | POST | `/api/v1/resource/heartbeat` | 資源心跳回報 | ✅ |
| 49 | GET | `/api/v1/resources` | 資源列表 | ✅ |

### 10. 統計與設定（Stats & Config）

| # | Method | Path | 說明 | 需 Key |
|---|--------|------|------|--------|
| 50 | GET | `/api/v1/stats/ingest` | 攝取統計（video/chunk 計數） | ✅ |
| 51 | GET | `/api/v1/stats/sftpgo` | SFTPGo 使用者狀態 | ✅ |
| 52 | GET | `/api/v1/stats/inference` | 推理叢集健康狀態 | ✅ |
| 53 | POST | `/api/v1/config/cache` | 切換快取開關 | ✅ |

---

## 未掛載的端點（定義了 handler 但未註冊路由）

| Handler | 位置 | 說明 |
|---------|------|------|
| `POST /api/v1/file/:file_uuid/face_trace/sortby` | `trace_agent_api.rs` | 定義了 `trace_agent_routes()` 但從未被 `server.rs` merge |

---

## 程式碼中存在 handler 但未註冊路由的端點

下列 handler 有實作但**沒有對應的 `.route()` 呼叫**，無法透過 HTTP 存取：

- `GET /api/v1/assets/:uuid/status` — `get_asset_status`
- `GET /api/v1/jobs/:job_id` — `get_job`
- `GET /api/v1/rules/:rule/status` — `get_rule_status`
- `GET /api/v1/videos/:uuid/details` — `video_details`
- `DELETE /api/v1/videos/:uuid` — `delete_video`
- `POST /api/v1/search` — `search`（語意搜尋）
- `POST /api/v1/search/hybrid` — `hybrid_search`
- `POST /api/v1/search/bm25` — `search_bm25`
- `GET /api/v1/lookup` — `lookup`
- `POST /api/v1/search/smart` — `search_smart`（server.rs 版，實際註冊的是 search.rs 版）

---

## 與 V1.0 文件的差異

V1.0 文件（`MOMENTRY_CORE_API_V1.0.0.md`）宣稱的端點中有以下**不存在於實際程式碼**：

| 文件宣稱 | 實際狀況 |
|----------|---------|
| `DELETE /api/v1/videos/:uuid` | handler 存在但未註冊路由 |
| `POST /api/v1/search` | handler 存在但未註冊路由 |
| `POST /api/v1/search/hybrid` | handler 存在但未註冊路由 |
| `POST /api/v1/assets/:uuid/process` | 實際是 `POST /api/v1/file/:file_uuid/process` |
| `GET /api/v1/files/:uuid/snapshots` | 不存在 |
| `POST /api/v1/files/:uuid/snapshots/migrate` | 不存在 |
| `GET /api/v1/face/list` | 不存在 |
| `POST /api/v1/face/recognize` | 不存在 |

---

## 路徑命名慣例

| 資源 | 路由格式 | 參數 |
|------|---------|------|
| 檔案 | `/api/v1/file/:file_uuid` | 32 碼 hex string |
| 身份 | `/api/v1/identity/:identity_uuid` | UUID v4 |
| 資源 | `/api/v1/resource/...` | - |

注意路徑使用**單數**（`file`, `identity`），與 RELEASE 文件的 `files`, `identities` 不同。
