---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core API 字典 V1.0.0"
date: "2026-05-06"
version: "V1.3"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "api"
  - "dictionary"
  - "v1.0.0"
ai_query_hints:
  - "Momentry Core API 字典查詢"
  - "API 端點與參數說明"
  - "API 回應格式定義"
  - "查詢所有 Public/Internal/Admin API 端點列表"
  - "API 端點的 HTTP 方法與路徑結構"
  - "搜尋 API 有哪些端點（search/bm25/hybrid/visual）"
  - "API 端點的狀態分類（Public/Internal/Admin）"
related_documents:
  - "API_V1.0.0/MOMENTRY_CORE_API_V1.0.0.md"
  - "API_V1.0.0/API_USAGE_DEMO_V1.0.0.md"
  - "API_V1.0.0/CHUNK_DEFINITION_V1.0.0.md"
  - "API_V1.0.0/VECTOR_SPEC_V1.0.0.md"
---

# Momentry Core API 字典 V1.0.0

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| Public API | 供前端與外部系統使用的標準介面 |
| Internal API | 系統內部流程或狀態查詢用 |
| Admin API | 管理員專用 |
| file_uuid | 32 碼 birth UUID（MAC + time + path + filename） |
| identity_uuid | 32 碼 UUIDv5（source + external_id） |
| RESTful | 以資源為中心的 API 設計風格，collection 複數、resource 單數 |

## 端點統計

| 分類 | 數量 | 說明 |
|---|---|---|
| Public | 40 | 供前端與外部系統使用的標準介面 |
| Internal | 4 | 系統內部流程或狀態查詢 |
| Admin | 3 | 管理員專用 |
| Health | 2 | 服務健康檢查 |
| **總計** | **48** | 所有已註冊路由 |

## 設計原則

### 1. RESTful 命名規範
- Collection（複數）: `/api/v1/files`, `/api/v1/identities`
- Resource（單數）: `/api/v1/file/:file_uuid`, `/api/v1/identity/:identity_uuid`
- Action on resource: `/api/v1/identity/:identity_uuid/bind`

### 2. File-Centric
- 每個媒體檔案由 32 碼 UUID (`file_uuid`) 唯一標識
- File 是所有資料的根節點，Chunk、Job 隸屬於特定 File

### 3. Global Identity
- Identity 跨檔案關聯，不受單一檔案限制
- 透過 bind/unbind/mergeinto 管理 Face → Identity 的直接 FK 綁定（V4.0）

---

## 1. 系統與認證

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/health` | Health |
| `GET` | `/health/detailed` | Health |
| `POST` | `/api/v1/auth/login` | Public |
| `POST` | `/api/v1/auth/logout` | Public |

## 2. 檔案管理 (Files)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/api/v1/files` | Public |
| `GET` | `/api/v1/files/scan` | Public |
| `POST` | `/api/v1/files/register` | Public |
| `POST` | `/api/v1/files/unregister` | Public |
| `GET` | `/api/v1/file/:file_uuid` | Public |
| `GET` | `/api/v1/file/:file_uuid/probe` | Public |
| `POST` | `/api/v1/file/:file_uuid/process` | Public |
| `GET` | `/api/v1/file/:file_uuid/identities` | Public |
| `GET` | `/api/v1/file/:file_uuid/chunks` | Public |
| `GET` | `/api/v1/file/:file_uuid/thumbnail?frame=&x=&y=&w=&h=` | Public |
| `POST` | `/api/v1/file/:file_uuid/face_trace/sortby` | Public |

## 3. 管線與任務 (Pipeline & Jobs)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/api/v1/progress/:file_uuid` | Public |
| `GET` | `/api/v1/jobs` | Public |
| `GET` | `/api/v1/job/:job_id` | Public |
| `GET` | `/api/v1/rule/:rule_id/status` | Public |
| `POST` | `/api/v1/resource/register` | Internal |
| `POST` | `/api/v1/resource/heartbeat` | Internal |
| `GET` | `/api/v1/resources` | Internal |

## 4. 搜尋 (Search)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `POST` | `/api/v1/search` | Public |
| `POST` | `/api/v1/search/bm25` | Public |
| `POST` | `/api/v1/search/hybrid` | Public |
| `POST` | `/api/v1/search/smart` | Public |
| `POST` | `/api/v1/search/universal` | Public |
| `POST` | `/api/v1/search/frames` | Public |
| `POST` | `/api/v1/search/visual` | Public |
| `POST` | `/api/v1/search/visual/class` | Public |
| `POST` | `/api/v1/search/visual/density` | Public |
| `POST` | `/api/v1/search/visual/combination` | Public |
| `POST` | `/api/v1/search/visual/stats` | Public |

## 5. 身份管理 (Identity)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/api/v1/identities` | Public |
| `POST` | `/api/v1/identity` | Public |
| `GET` | `/api/v1/identity/:identity_uuid` | Public |
| `DELETE` | `/api/v1/identity/:identity_uuid` | Public |
| `GET` | `/api/v1/identity/:identity_uuid/files` | Public |
| `GET` | `/api/v1/identity/:identity_uuid/chunks` | Public |
| `POST` | `/api/v1/identity/:identity_uuid/bind` | Public |
| `POST` | `/api/v1/identity/:identity_uuid/unbind` | Public |
| `POST` | `/api/v1/identity/:from_uuid/mergeinto` | Public |

## 6. 臉部 (Faces)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/api/v1/faces/candidates` | Public |

## 7. 代理人 (Agents)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `POST` | `/api/v1/agents/translate` | Public |
| `POST` | `/api/v1/agents/identity/analyze` | Public |
| `POST` | `/api/v1/agents/identity/suggest` | Public |
| `GET` | `/api/v1/agents/identity/status` | Public |
| `POST` | `/api/v1/agents/suggest/merge` | Public |
| `POST` | `/api/v1/agents/5w1h/analyze` | Public |
| `POST` | `/api/v1/agents/5w1h/batch` | Public |
| `GET` | `/api/v1/agents/5w1h/status` | Public |

## 8. 狀態與管理 (Stats & Admin)

| 方法 | 路徑 | 狀態 |
|------|------|------|
| `GET` | `/api/v1/stats/sftpgo` | Internal |
| `GET` | `/api/v1/stats/inference` | Internal |
| `POST` | `/api/v1/config/cache` | Admin |

---

## 變更歷史

| 版本 | 日期 | 作者 | 說明 |
|------|------|------|------|
| V1.3 | 2026-05-06 | OpenCode | 新增 `face_thumbnail` ffmpeg 即時裁切端點 + `face_trace/sortby` 端點；portal 修復 hardcoded URL/API key/legacy endpoints |
| V1.1 | 2026-05-01 | OpenCode | Route fixes + arch notes |
| V1.0 | 2026-04 | OpenCode | 初始版本 |
