docs: rewrite RELEASE_API_REFERENCE v4.0 - 55 endpoints, 10 categories

2026-05-08 04:16:39 +08:00
parent 8c9bab1d4a
commit cad5eadeec
1 changed files with 165 additions and 304 deletions
--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
@@ -1,354 +1,215 @@
 ---
 document_type: "reference_doc"
 service: "MOMENTRY_CORE"
-title: "Momentry Core Release API 參考文件 V1.0.0 (V3 legacy)"
-date: "2026-05-03"
-deprecated: true
---
-
-> ⚠️ **此文件為 V3.x 歷史參考，含已移除的路由。**
-> 請改用 `API_DICTIONARY_V1.0.0.md`（root）取得當前準確的 53 條 API 路由。
+title: "Momentry Core Release API Reference v1.0.0"
+date: "2026-05-08"
 version: "V4.0"
-status: "outdated"
+status: "active"
 owner: "Warren"
-created_by: "OpenCode"
-tags:
-  - "api"
-  - "reference"
-  - "release"
-  - "v1.0.0"
-  - "marcom"
-  - "production"
-ai_query_hints:
-  - "Momentry Core Release API 完整列表"
-  - "API 認證方式與 Base URL（port 3002）"
-  - "檔案註冊、處理、搜尋、臉部綁定流程"
-  - "錯誤回應格式（401/400/404）"
-related_documents:
-  - "RELEASE/RELEASE_VERIFICATION_V1.0.0.md"
-  - "RELEASE/PRODUCTION_VERIFICATION_V1.0.0.md"
 ---

-# Momentry Core Release API 參考文件 V1.0.0
+# Momentry Core API Reference v1.0.0

-| 項目 | 內容 |
-|------|------|
-| 建立者 | OpenCode |
-| 建立時間 | 2026-05-03 |
-| 文件版本 | V4.0 |
-| Base URL | `http://localhost:3002` |
+56 endpoints across 10 categories.

---
+## Base

-## 版本歷史
+| Environment | URL |
+|-------------|-----|
+| Production | `http://localhost:3002` or `https://api.momentry.ddns.net` |
+| Development | `http://localhost:3003` |
+| Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |

-| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
-|------|------|------|--------|-----------|
-| V4.0 | 2026-05-03 | Release 版本：完整 78 端點 API 參考文件 | OpenCode | deepseek-chat |
+## 1. System (server.rs)

---
-
-## 認證方式
-
- **Header**: `X-API-Key: <your_api_key>`
- 未提供或無效的 key 回傳 `401 Unauthorized`
- 所有端點（除 `/health` 與 `/health/detailed` 外）都需要 API key
-
---
-
-## 錯誤回應格式
-
-```json
-// 401 Unauthorized
-{ "error": "Unauthorized", "message": "Invalid or missing API key" }
-
-// 400 Bad Request
-{ "error": "Bad Request", "message": "Missing required field: file_path" }
-
-// 404 Not Found
-{ "error": "Not Found", "message": "Video not found: <uuid>" }
-```
-
---
-
-## 端點列表
-
-### 1. 系統與認證
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 1 | GET | `/health` | 系統健康檢查（無需 API key） |
-| 2 | GET | `/health/detailed` | 詳細健康狀態（無需 API key） |
-| 3 | POST | `/api/v1/auth/login` | 登入 |
-| 4 | POST | `/api/v1/auth/logout` | 登出 |
-
-### 2. 檔案管理
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 5 | GET | `/api/v1/files` | 檔案列表 |
-| 6 | GET | `/api/v1/files/:uuid` | 檔案詳細資訊 |
-| 7 | GET | `/api/v1/files/scan` | 掃描目錄中的新檔案 |
-| 8 | POST | `/api/v1/files/register` | 註冊檔案 |
-| 9 | POST | `/api/v1/unregister` | 取消註冊檔案 |
-| 10 | GET | `/api/v1/files/:file_uuid/probe` | 探測檔案資訊（ffprobe） |
-| 11 | POST | `/api/v1/files/:file_uuid/process` | 啟動處理 pipeline |
-| 12 | GET | `/api/v1/assets/:uuid/status` | 資產處理狀態 |
-| 13 | GET | `/api/v1/progress/:uuid` | 處理進度查詢 |
-| 14 | GET | `/api/v1/videos/:uuid/details` | 影片詳細資料（含 chunks/pre_chunks） |
-| 15 | GET | `/api/v1/videos/:uuid/pre_chunks` | 影片 pre_chunks 列表 |
-| 16 | DELETE | `/api/v1/videos/:uuid` | 刪除影片 |
-
-### 3. 任務與佇列
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 17 | GET | `/api/v1/jobs` | 任務列表 |
-| 18 | GET | `/api/v1/jobs/:job_id` | 任務狀態 |
-| 19 | GET | `/api/v1/rules/:rule/status` | Rule 處理狀態 |
-
-### 4. 搜尋
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 20 | POST | `/api/v1/search` | 全文搜尋 |
-| 21 | POST | `/api/v1/search/hybrid` | 混合搜尋（向量 + BM25） |
-| 22 | POST | `/api/v1/search/bm25` | BM25 全文檢索 |
-| 23 | POST | `/api/v1/search/universal` | 通用搜尋 |
-| 24 | POST | `/api/v1/smart` | 智慧搜尋（多輪對話） |
-| 25 | POST | `/api/v1/search/visual` | 視覺搜尋 |
-| 26 | POST | `/api/v1/search/visual/class` | 視覺分類搜尋（依物件類別） |
-| 27 | POST | `/api/v1/search/visual/density` | 視覺密度搜尋 |
-| 28 | POST | `/api/v1/search/visual/stats` | 視覺統計 |
-| 29 | POST | `/api/v1/search/visual/combination` | 視覺組合搜尋 |
-| 30 | POST | `/api/v1/search/frames` | 影格搜尋 |
-| 31 | GET | `/api/v1/search/persons` | 人物搜尋 |
-| 32 | GET | `/api/v1/lookup` | UUID 查詢 |
-
-### 5. 身份（Identity）
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 33 | GET | `/api/v1/identities` | 身份列表 |
-| 34 | GET | `/api/v1/identities/:uuid` | 身份詳細資訊 |
-| 35 | GET | `/api/v1/identities/:uuid/files` | 身份相關檔案 |
-| 36 | GET | `/api/v1/identities/:uuid/chunks` | 身份相關 chunks |
-| 37 | POST | `/api/v1/identities/bind` | 綁定身份 |
-| 38 | POST | `/api/v1/identities/unbind` | 解除綁定 |
-| 39 | POST | `/api/v1/identities/suggest-av` | 建議音視綁定 |
-| 40 | POST | `/api/v1/identities/from-face` | 從臉部建立身份 |
-| 41 | POST | `/api/v1/identities/from-person` | 從人物建立身份 |
-| 42 | GET | `/api/v1/identity/:binding_type/:binding_value` | 依 binding 查詢身份 |
-
-### 6. 臉部（Face）
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 43 | GET | `/api/v1/faces/candidates` | 臉部候選列表 |
-| 44 | POST | `/api/v1/face/recognize` | 臉部辨識 |
-| 45 | POST | `/api/v1/face/register` | 註冊臉部 |
-| 46 | POST | `/api/v1/face/search` | 臉部搜尋 |
-| 47 | GET | `/api/v1/face/list` | 臉部列表 |
-| 48 | GET | `/api/v1/face/results/:file_uuid` | 臉部辨識結果 |
-| 49 | GET | `/api/v1/files/:file_uuid/faces/:face_id` | 臉部詳細資訊 |
-| 50 | DELETE | `/api/v1/files/:file_uuid/faces/:face_id` | 刪除臉部 |
-| 51 | GET | `/api/v1/files/:file_uuid/faces/:face_id/thumbnail` | 臉部縮圖 |
-
-### 7. 信號（Signal）
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 52 | GET | `/api/v1/signals/unbound` | 未綁定信號列表 |
-| 53 | GET | `/api/v1/signals/:uuid/:binding_type/:binding_value/timeline` | 信號時間軸 |
-
-### 8. 檔案身份關聯
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 54 | GET | `/api/v1/files/:uuid/identities` | 檔案的身份列表 |
-
-### 9. 快照（Snapshot）
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 55 | GET | `/api/v1/files/:uuid/snapshots` | 取得檔案快照 |
-| 56 | POST | `/api/v1/files/:uuid/snapshots` | 產生檔案快照 |
-| 57 | GET | `/api/v1/files/:uuid/snapshots/status` | 快照處理狀態 |
-| 58 | POST | `/api/v1/files/:uuid/snapshots/migrate` | 遷移快照 |
-| 59 | POST | `/api/v1/files/:uuid/snapshots/teardown` | 刪除快照 |
-| 60 | GET | `/api/v1/identities/:uuid/snapshots` | 取得身份快照 |
-| 61 | POST | `/api/v1/identities/:uuid/snapshots` | 產生身份快照 |
-
-### 10. Agent
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 62 | POST | `/api/v1/agents/translate` | 翻譯 Agent |
-| 63 | POST | `/api/v1/agents/identity/analyze` | 身份分析 Agent |
-| 64 | POST | `/api/v1/agents/identity/suggest` | 身份合併建議 |
-| 65 | GET | `/api/v1/agents/identity/status` | 身份 Agent 狀態 |
-| 66 | POST | `/api/v1/agents/suggest/clustering` | 聚類建議 |
-| 67 | POST | `/api/v1/agents/suggest/merge` | 合併建議 |
-| 68 | POST | `/api/v1/agents/5w1h/analyze` | 5W1H 分析 |
-| 69 | POST | `/api/v1/agents/5w1h/batch` | 5W1H 批量分析 |
-| 70 | GET | `/api/v1/agents/5w1h/status` | 5W1H 狀態 |
-
-### 11. 資源（Resource）
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 71 | POST | `/api/v1/resources/register` | 註冊資源 |
-| 72 | POST | `/api/v1/resources/heartbeat` | 資源心跳 |
-| 73 | GET | `/api/v1/resources` | 資源列表 |
-
-### 12. 統計與設定
-
-| # | Method | Path | 說明 |
-|---|--------|------|------|
-| 74 | GET | `/api/v1/stats/ingest` | 攝取統計 |
-| 75 | GET | `/api/v1/stats/sftpgo` | SFTPGo 狀態 |
-| 76 | GET | `/api/v1/stats/inference` | 推理健康狀態 |
-| 77 | POST | `/api/v1/config/cache` | 快取切換 |
-
---
-
-## 端點範例
-
-### GET /health
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 1 | GET | `/health` | Server status (ok/degraded) | `server.rs:2529` |
+| 2 | GET | `/health/detailed` | Per-service health + latency | `server.rs:2530` |
+| 3 | POST | `/api/v1/auth/login` | Username/password → API key | `server.rs:2531` |
+| 4 | POST | `/api/v1/auth/logout` | Invalidate session | `server.rs:2532` |
+| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | `server.rs:2533` |
+| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status | `server.rs:2534` |
+| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health | `server.rs:2535` |
+| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache | `server.rs:2513` |

+**Example:**
 ```bash
-curl http://localhost:3002/health
+GET /health
+→ {"status":"ok","version":"1.0.0","uptime_ms":248233}
+
+GET /health/detailed
+→ {"status":"ok","services":{"postgres":{"status":"ok","latency_ms":3}},...}
 ```

-```json
-{
-  "status": "ok",
-  "version": "1.0.0 (build: ...)",
-  "uptime_ms": 189049
-}
-```
+## 2. File Management (server.rs)

-### POST /api/v1/files/register
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 9 | POST | `/api/v1/files/register` | Register video → UUID | `server.rs:2505` |
+| 10 | POST | `/api/v1/unregister` | Delete file + all data | `server.rs:2506` |
+| 11 | GET | `/api/v1/files/scan` | Scan directory for new files | `server.rs:2507` |
+| 12 | GET | `/api/v1/file/:file_uuid` | Single file detail | `identity_api.rs:16` |
+| 13 | GET | `/api/v1/files` | List files (paginated) | `identity_api.rs:15` |
+| 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | `server.rs:2508` |
+| 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | `server.rs:2509` |
+| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks | `server.rs:2510` |
+| 17 | GET | `/api/v1/progress/:uuid` | Processing progress | `server.rs:2511` |
+| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | `server.rs:2512` |

+**Example:**
 ```bash
-curl -X POST http://localhost:3002/api/v1/files/register \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: <your_api_key>" \
-  -d '{"file_path": "/path/to/video.mp4"}'
+POST /api/v1/files/register
+{"file_path":"/sftpgo/data/demo/video.mp4"}
+→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0,...}
+
+GET /api/v1/files?page=1&page_size=5
+→ {"files":[...],"total":37,"page":1}
 ```

-```json
-{
-  "success": true,
-  "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
-  "file_name": "video.mp4",
-  "duration": 120.5,
-  "width": 1920,
-  "height": 1080,
-  "fps": 30.0
-}
-```
+## 3. Search (server.rs + search.rs + universal_search.rs)

-### POST /api/v1/search
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 19 | POST | `/api/v1/search/visual` | Visual chunk search | `server.rs:2536` |
+| 20 | POST | `/api/v1/search/visual/class` | By object class | `server.rs:2541` |
+| 21 | POST | `/api/v1/search/visual/density` | By spatial density | `server.rs:2546` |
+| 22 | POST | `/api/v1/search/visual/combination` | Combined visual search | `server.rs:2541` |
+| 23 | POST | `/api/v1/search/visual/stats` | Visual stats | `server.rs:2545` |
+| 24 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | `search.rs:164` |
+| 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires uuid) | `universal_search.rs:94` |
+| 26 | POST | `/api/v1/search/frames` | Frame-level search | `universal_search.rs:95` |

+**Example:**
 ```bash
-curl -X POST http://localhost:3002/api/v1/search \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: <your_api_key>" \
-  -d '{"query": "關鍵字", "uuid": "<file_uuid>"}'
+POST /api/v1/search/universal
+{"query":"friends","mode":"bm25","uuid":"3abeee81..."}
+→ {"count":1,"results":[{"text":"You won't find it difficult to make some new friends.",...}]}
+
+POST /api/v1/search/smart
+{"query":"Audrey Hepburn","uuid":"3abeee81..."}
+→ {"strategy":"semantic_vector_search","results":[...]}
 ```

-```json
-{
-  "results": [
-    {
-      "chunk_id": "chunk_42",
-      "text": "轉錄文字內容",
-      "start_time": 12.5,
-      "end_time": 15.3,
-      "score": 0.89
-    }
-  ],
-  "total": 1
-}
-```
+## 4. Face Trace (trace_agent_api.rs)

-### GET /api/v1/progress/:uuid
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 27 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) | `trace_agent_api.rs:14` |
+| 28 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Trace detections (+ interpolation) | `trace_agent_api.rs:18` |

+**Parameters:**
+- `sort_by`: `face_count` | `duration` | `first_appearance`
+- `min_faces`, `min_confidence`, `max_confidence`: filters
+- `interpolate=true`: fills sparse gaps with lerp bbox
+
+**Example:**
 ```bash
-curl http://localhost:3002/api/v1/progress/<file_uuid> \
-  -H "X-API-Key: <your_api_key>"
+POST /api/v1/file/3abeee81.../face_trace/sortby
+{"sort_by":"face_count","limit":3}
+→ {"total_traces":6892,"total_faces":108204,
+   "traces":[{"trace_id":3128,"face_count":1109,...}]}
+
+GET /api/v1/file/3abeee81.../trace/2/faces?limit=3&interpolate=true
+→ {"faces":[{"start_frame":4620,"interpolated":false,...}]}
 ```

-```json
-{
-  "uuid": "<file_uuid>",
-  "overall_progress": 65,
-  "processors": [
-    {"name": "cut", "status": "completed", "progress": 100},
-    {"name": "asr", "status": "running", "progress": 50},
-    {"name": "yolo", "status": "pending", "progress": 0}
-  ]
-}
-```
+## 5. Media (media_api.rs)

-### POST /api/v1/identities/bind
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 29 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (optional crop) | `media_api.rs:23` |
+| 30 | GET | `/api/v1/file/:uuid/video` | Raw video stream | `media_api.rs:18` |
+| 31 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video | `media_api.rs:14` |
+| 32 | GET | `/api/v1/file/:uuid/trace/:id/video` | Trace clip with bbox | `media_api.rs:22` |

+**Parameters:**
+- `thumbnail`: `?frame=4650&x=0&y=0&w=100&h=100`
+- `video`: `?start=0&end=300` (seconds)
+- `video/bbox`: `?start=0&end=300&duration=10`
+- `trace/:id/video`: `?padding=2.0`
+
+## 6. Identities (identity_api.rs + identities.rs)
+
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 33 | GET | `/api/v1/identities` | List all identities | `identity_api.rs:17` |
+| 34 | GET | `/api/v1/file/:uuid/identities` | Identities in a file | `identity_api.rs:21` |
+| 35 | POST | `/api/v1/identity` | Register new identity | `identities.rs:34` |
+| 36 | GET | `/api/v1/identity/:uuid` | Identity detail | `identity_api.rs:25` |
+| 37 | DELETE | `/api/v1/identity/:uuid` | Delete identity | `identity_api.rs:29` |
+| 38 | GET | `/api/v1/identity/:uuid/files` | Files for identity | `identity_api.rs:33` |
+| 39 | GET | `/api/v1/identity/:uuid/chunks` | Chunks for identity | `identity_api.rs:34` |
+| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery | `identities.rs:35` |
+
+**Example:**
 ```bash
-curl -X POST http://localhost:3002/api/v1/identities/bind \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: <your_api_key>" \
-  -d '{"identity_id": 1, "binding_type": "face", "binding_value": "<face_id>"}'
+GET /api/v1/identities?page=1&page_size=5
+→ {"identities":[{"name":"Cary Grant","tmdb_id":...,}],...}
 ```

-```json
-{
-  "success": true,
-  "message": "Bound face '<face_id>' to Identity '<name>'"
-}
-```
+## 7. Identity Binding (identity_binding.rs)

-### GET /api/v1/files/:file_uuid/faces/:face_id/thumbnail
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 41 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity | `identity_binding.rs:291` |
+| 42 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity | `identity_binding.rs:292` |
+| 43 | POST | `/api/v1/identity/:from/mergeinto` | Merge two identities | `identity_binding.rs:296` |

+**Example:**
 ```bash
-curl -o thumbnail.jpg http://localhost:3002/api/v1/files/<file_uuid>/faces/<face_id>/thumbnail \
-  -H "X-API-Key: <your_api_key>"
+POST /api/v1/identity/a9a90105.../bind
+{"file_uuid":"3abeee81...","face_id":"face_42"}
+→ {"success":true}
 ```

-回傳 JPEG 二進位資料。
+## 8. Resources (identity_api.rs)

-### GET /api/v1/identities
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 44 | POST | `/api/v1/resource/register` | Register processing resource | `identity_api.rs:35` |
+| 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | `identity_api.rs:34` |
+| 46 | GET | `/api/v1/resources` | List all resources | `identity_api.rs:33` |

-```bash
-curl "http://localhost:3002/api/v1/identities?page=1&page_size=20" \
-  -H "X-API-Key: <your_api_key>"
-```
+## 9. Agents — 5W1H (five_w1h_agent_api.rs)

-```json
-{
-  "identities": [
-    {"id": 1, "name": "張三", "binding_count": 5}
-  ],
-  "count": 15
-}
-```
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 47 | POST | `/api/v1/agents/translate` | AI text translation | `agent_api.rs:8` |
+| 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | `five_w1h_agent_api.rs:20` |
+| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | `five_w1h_agent_api.rs:21` |
+| 50 | GET | `/api/v1/agents/5w1h/status` | Job status | `five_w1h_agent_api.rs:22` |
+
+## 10. Agents — Identity (identity_agent_api.rs)
+
+| # | Method | Path | Description | File:Line |
+|---|--------|------|-------------|-----------|
+| 51 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | `identity_agent_api.rs:17` |
+| 52 | GET | `/api/v1/agents/identity/status` | Analysis status | `identity_agent_api.rs:19` |
+| 53 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | `identity_agent_api.rs:20` |
+| 54 | POST | `/api/v1/agents/suggest/merge` | Suggest identity merge | `identity_agent_api.rs` |
+| 55 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | `identity_agent_api.rs` |

 ---

-## 常見錯誤
+## Summary

-| HTTP 狀態 | 原因 | 解決方式 |
-|-----------|------|----------|
-| 401 | 缺少或無效的 API key | 確認 header `X-API-Key` 已設定 |
-| 400 | 請求參數錯誤 | 檢查必要欄位是否遺漏 |
-| 404 | 資源不存在 | 確認 file_uuid / identity_id 是否正確 |
-| 500 | 伺服器內部錯誤 | 聯繫系統管理員 |
+| Category | Routes | Source |
+|----------|--------|--------|
+| System | 8 | `server.rs` |
+| File Management | 10 | `server.rs`, `identity_api.rs` |
+| Search | 8 | `server.rs`, `search.rs`, `universal_search.rs` |
+| Face Trace | 2 | `trace_agent_api.rs` |
+| Media | 4 | `media_api.rs` |
+| Identities | 8 | `identity_api.rs`, `identities.rs` |
+| Binding | 3 | `identity_binding.rs` |
+| Resources | 3 | `identity_api.rs` |
+| Agents (5W1H) | 4 | `five_w1h_agent_api.rs`, `agent_api.rs` |
+| Agents (Identity) | 5 | `identity_agent_api.rs` |
+| **Total** | **55** | |

---
+## Related

-## 重要備註
-
- `/:uuid` 與 `/:file_uuid` 均為 32 碼 hex string
- Process 為非同步操作，完成後需透過 Progress 端點輪詢
- 搜尋端點回傳結果包含 `score`（0.0~1.0），越高越相關
- 臉部縮圖端點回傳 JPEG binary，非 JSON
+- `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints)
+- `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples
+- `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference