From a19385d35bc10d5de0d8e09762f749e43ab653ed Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Fri, 8 May 2026 02:54:18 +0800
Subject: [PATCH] docs: add missing trace routes to API_DOCUMENTATION, mark V3
 docs deprecated

---
 .../API_V1.0.0/API_DOCUMENTATION_v1.0.0.md    | 76 ++++++++++++++++++-
 .../INTERNAL/DEV_API_REFERENCE_v1.0.0.md      |  6 +-
 .../RELEASE/RELEASE_API_REFERENCE_v1.0.0.md   |  7 +-
 3 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_v1.0.0.md b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_v1.0.0.md
index 1539e4b..bf35699 100644
--- a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_v1.0.0.md
@@ -354,7 +354,81 @@ Query: ?padding=1
 
 Returns `video/mp4` binary. Shows face trace with ID label held at last detection position.
 
-### 3.4 Thumbnail
+### 3.4 Trace List (Sorted/Filtered)
+
+Returns aggregated face traces for a file, with sorting and filtering.
+
+```
+POST /api/v1/file/{file_uuid}/face_trace/sortby
+Content-Type: application/json
+
+{
+  "sort_by": "face_count | duration | first_appearance",
+  "limit": 100,
+  "min_faces": 1,
+  "min_confidence": 0.0,
+  "max_confidence": 1.0
+}
+```
+
+Response:
+```json
+{
+  "success": true,
+  "file_uuid": "...",
+  "total_traces": 6892,
+  "total_faces": 108204,
+  "traces": [
+    {
+      "trace_id": 3128,
+      "face_count": 1109,
+      "first_frame": 68280,
+      "last_frame": 69240,
+      "first_sec": 2731.2,
+      "last_sec": 2769.6,
+      "duration_sec": 38.4,
+      "avg_confidence": 0.78,
+      "sample_face_id": "18441"
+    }
+  ]
+}
+```
+
+### 3.5 Trace Face Detections
+
+Returns individual face detections for a specific trace, with optional linear interpolation.
+
+```
+GET /api/v1/file/{file_uuid}/trace/{trace_id}/faces
+Query: ?limit=200&offset=0&interpolate=false
+```
+
+When `interpolate=true`, frames between sparse detections are filled with linear bbox interpolation (id=0, confidence=0.0, interpolated=true).
+
+Response:
+```json
+{
+  "success": true,
+  "file_uuid": "...",
+  "trace_id": 2,
+  "total": 2,
+  "faces": [
+    {
+      "id": 12400,
+      "start_frame": 4650,
+      "start_time": 186.0,
+      "x": 1047,
+      "y": 361,
+      "width": 187,
+      "height": 187,
+      "confidence": 0.834,
+      "interpolated": false
+    }
+  ]
+}
+```
+
+### 3.6 Thumbnail
 
 Extracts a single frame as JPEG thumbnail.
 
diff --git a/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md b/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md
index a8acc2a..57e6bf2 100644
--- a/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md
@@ -4,8 +4,12 @@ service: "MOMENTRY_CORE"
 title: "Momentry Core Dev API 參考文件"
 date: "2026-05-06"
 version: "V1.1"
-status: "active"
+status: "deprecated"
 owner: "Warren"
+---
+
+> ⚠️ **此文件為 V3.x 歷史參考，含已移除的路由。**
+> 請改用 `API_DICTIONARY_V1.0.0.md`（root）取得當前準確的 53 條 API 路由。
 created_by: "OpenCode"
 tags:
   - "api"
diff --git 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
index 633601a..121209c 100644
--- 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,8 +1,13 @@
 ---
 document_type: "reference_doc"
 service: "MOMENTRY_CORE"
-title: "Momentry Core Release API 參考文件 V1.0.0"
+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 路由。
 version: "V4.0"
 status: "outdated"
 owner: "Warren"