docs: audit API docs — fix all remaining bare uuid → file_uuid

2026-05-14 17:54:39 +08:00
parent a9d0228a72
commit 0491c39d3f
12 changed files with 130 additions and 56 deletions
--- a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION.md
+++ b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION.md
@@ -85,7 +85,7 @@ X-API-Key: <key>
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "file_path": null,
  "pattern": null
 }
@@ -95,7 +95,7 @@ Response `200`:
 ```json
 {
  "success": true,
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "message": "File unregistered successfully",
  "deleted_face_detections": 6186,
  "deleted_processor_results": 42,
@@ -231,7 +231,7 @@ Response `200`:
  "jobs": [
    {
      "id": 139,
-      "uuid": "32-char-hex-string",
+      "file_uuid": "32-char-hex-string",
      "status": "completed",
      "current_processor": null
    }
@@ -418,7 +418,7 @@ Response `200`:
 ```json
 {
  "success": true,
-  "uuid": "identity-uuid",
+  "file_uuid": "identity-uuid",
  "name": "Cary Grant",
  "identity_type": "actor",
  "source": "tmdb",
@@ -527,7 +527,7 @@ Content-Type: application/json

 {
  "query": "Cary Grant",
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "types": ["chunk", "frame", "person"],
  "time_range": null,
  "filters": null,
@@ -569,7 +569,7 @@ POST /api/v1/search/smart
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "query": "who said how do you shave in there?",
  "limit": 10
 }
@@ -605,7 +605,7 @@ POST /api/v1/search/frames
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "object_class": "person",
  "ocr_text": "welcome",
  "face_id": null,
@@ -641,7 +641,7 @@ POST /api/v1/search/visual
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "criteria": {
    "min_unique_classes": 2,
    "required_classes": ["person", "car"]
@@ -675,7 +675,7 @@ POST /api/v1/search/visual/class
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "object_class": "car",
  "min_count": 1,
  "max_count": 10
@@ -708,7 +708,7 @@ POST /api/v1/search/visual/density
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "min_density": 0.1,
  "max_density": 0.8
 }
@@ -739,14 +739,14 @@ POST /api/v1/search/visual/stats
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string"
+  "file_uuid": "32-char-hex-string"
 }
 ```

 Response `200`:
 ```json
 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "stats": {
    "total_chunks": 45,
    "total_frames": 18000,
@@ -763,7 +763,7 @@ POST /api/v1/search/visual/combination
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "combination": [["person", 1], ["car", 1]]
 }
 ```
--- 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
@@ -85,7 +85,7 @@ X-API-Key: <key>
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "file_path": null,
  "pattern": null
 }
@@ -95,7 +95,7 @@ Response `200`:
 ```json
 {
  "success": true,
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "message": "File unregistered successfully",
  "deleted_face_detections": 6186,
  "deleted_processor_results": 42,
--- 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
@@ -85,7 +85,7 @@ X-API-Key: <key>
 Content-Type: application/json

 {
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "file_path": null,
  "pattern": null
 }
@@ -95,7 +95,7 @@ Response `200`:
 ```json
 {
  "success": true,
-  "uuid": "32-char-hex-string",
+  "file_uuid": "32-char-hex-string",
  "message": "File unregistered successfully",
  "deleted_face_detections": 6186,
  "deleted_processor_results": 42,
@@ -269,7 +269,7 @@ Response `200`:

 ```
 GET /api/v1/files
-Query: ?page=1&page_size=10&uuid=xxx
+Query: ?page=1&page_size=10&file_uuid=xxx
 ```

 Response `200`:
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
@@ -96,7 +96,7 @@ curl http://localhost:3002/health/detailed
 | # | Method | Path | Description |
 |---|--------|------|-------------|
 | 9 | POST | `/api/v1/files/register` | Register video → file_uuid |
-| 10 | POST | `/api/v1/unregister` | Unregister file(s): by `uuid` or pattern match (`file_path`+`pattern`) |
+| 10 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
 | 11 | GET | `/api/v1/files/scan` | Scan directory for new files |
 | 12 | GET | `/api/v1/files` | List files (paginated) |
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
@@ -114,7 +114,7 @@ curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_6
 ```

 Modes:
- By `uuid`: unregister a single file
+- By `file_uuid`: unregister a single file
 - By `file_path` + `pattern` regex: unregister all matching files in a directory

 ```bash
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
@@ -2,15 +2,15 @@
 document_type: "reference_doc"
 service: "MOMENTRY_CORE"
 title: "Momentry Core Release API Reference v1.0.0"
-date: "2026-05-08"
-version: "V4.0"
+date: "2026-05-14"
+version: "V4.1"
 status: "active"
 owner: "Warren"
 ---

 # Momentry Core API Reference v1.0.0

-56 endpoints across 10 categories, with real curl examples and responses.
+58 endpoints across 10 categories, with real curl examples and responses.

 ## Base

@@ -41,7 +41,52 @@ owner: "Warren"
 curl http://localhost:3002/health
 ```
 ```json
-{"status":"ok","version":"1.0.0","uptime_ms":7052517}
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "build_git_hash": "26f2434",
+  "build_timestamp": "2026-05-14T09:09:17Z",
+  "uptime_ms": 7052517
+}
+```
+
+| # | Method | Path | Description |
+|---|--------|------|-------------|
+| 2a | GET | `/health/detailed` | Per-service health + resources + pipeline |
+
+```bash
+curl http://localhost:3002/health/detailed
+```
+```json
+{
+  "status": "ok",
+  "build_git_hash": "26f2434",
+  "build_timestamp": "2026-05-14T09:09:17Z",
+  "services": {
+    "postgres": {"status": "ok", "latency_ms": 6},
+    "redis":    {"status": "ok", "latency_ms": 0},
+    "qdrant":   {"status": "ok", "latency_ms": 1},
+    "mongodb":  {"status": "ok", "latency_ms": 0}
+  },
+  "resources": {
+    "cpu_used_percent": 50.0,
+    "cpu_idle_percent": 50.0,
+    "memory_available_mb": 8028,
+    "memory_total_mb": 16384,
+    "memory_used_percent": 51.0,
+    "gpu_available": false,
+    "gpu_utilization": null,
+    "gpu_memory_used_pct": null
+  },
+  "pipeline": {
+    "scripts": true,
+    "models": true,
+    "ffmpeg": true,
+    "embedding_server": {"status": "ok", "latency_ms": 0},
+    "gdino_api":        {"status": "error", "latency_ms": 0, "error": "..."},
+    "llm":              {"status": "ok", "latency_ms": 0}
+  }
+}
 ```

 ---
@@ -51,7 +96,7 @@ curl http://localhost:3002/health
 | # | Method | Path | Description |
 |---|--------|------|-------------|
 | 9 | POST | `/api/v1/files/register` | Register video → file_uuid |
-| 10 | POST | `/api/v1/unregister` | Delete file + all data |
+| 10 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
 | 11 | GET | `/api/v1/files/scan` | Scan directory for new files |
 | 12 | GET | `/api/v1/files` | List files (paginated) |
 | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
@@ -68,14 +113,23 @@ curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_6
 {"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0}
 ```

+Modes:
+- By `file_uuid`: unregister a single file
+- By `file_path` + `pattern` regex: unregister all matching files in a directory
+
 ```bash
+# By file_uuid
 curl -X POST http://localhost:3002/api/v1/unregister \
-  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
-  -H "Content-Type: application/json" \
-  -d '{"uuid":"53e3a229bf68878b7a799e811e097f9c"}'
+  -H "X-API-Key: muser_..." -H "Content-Type: application/json" \
+  -d '{"file_uuid":"53e3a229bf68878b7a799e811e097f9c"}'
+
+# By pattern (unregister all .mp4 files in directory)
+curl -X POST http://localhost:3002/api/v1/unregister \
+  -H "X-API-Key: muser_..." -H "Content-Type: application/json" \
+  -d '{"file_path":"/data/demo","pattern":"\\.mp4$"}'
 ```
 ```json
-{"success":true,"uuid":"53e3a229bf68878b7a799e811e097f9c","message":"File unregistered successfully"}
+{"success":true,"file_uuid":"53e3a229bf68878b7a799e811e097f9c","message":"File unregistered successfully"}
 ```

 ```bash
@@ -162,19 +216,31 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2
 | # | Method | Path | Description |
 |---|--------|------|-------------|
 | 29 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
-| 30 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (?start=&end=) |
-| 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (?start=&end=&duration=) |
-| 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?padding=) |
+| 30 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (`?start_time=&end_time=` seconds) |
+| 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (`?start_frame=&end_frame=&face_uuid=&duration=` frames) |
+| 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=) |
+
+Two modes:
+- `mode=normal` (default): raw clip, `-c copy`, no overlay
+- `mode=debug`: text overlay + green bounding boxes

 ```bash
-curl -o thumb.jpg "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/thumbnail?frame=4650"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
+# Normal mode
+curl -o trace.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=normal"
+# Debug mode
+curl -o trace_debug.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=debug"
 ```
-Returns JPEG binary (82KB, 1920×1080).

-```bash
-curl -o trace_clip.mp4 "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/video"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
+Debug overlay shows at bottom-left:
 ```
-Returns MP4 video binary (3.0MB) with bbox overlay.
+Frame {n}  {pts}s
+Cut: {id}
+{file_uuid}
+Trace {id}: start={frame}  {name}
+...
+```
+
+Green bbox per face detection: actual frames `thickness=4`, interpolated `thickness=1`.

 ---

@@ -190,6 +256,8 @@ Returns MP4 video binary (3.0MB) with bbox overlay.
 | 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
 | 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
 | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
+| 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
+| 42 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |

 ```bash
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -217,7 +285,7 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2"  -H "X-A
 |---|--------|------|-------------|
 | 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
 | 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
-| 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities |
+| 43 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |

 ```bash
 curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'
@@ -275,8 +343,14 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: mus

 ---

+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| V4.1 | 2026-05-14 | Added `build_timestamp` + `resources` + `pipeline` to health APIs; identity search endpoints; trace debug rework (green bbox, text overlay, all traces listed) |
+
 ## Related

- `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints)
+- `API_DICTIONARY_V1.0.0.md` — Quick reference (58 endpoints)
 - `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples
 - `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference
--- a/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md
@@ -129,7 +129,7 @@ erDiagram
    IDENTITIES {
        int id PK
        string name
-        string uuid
+        string file_uuid
        int tmdb_id
    }
 ```
@@ -189,9 +189,9 @@ sequenceDiagram
 ```mermaid
 sequenceDiagram
    actor Dev
-    Dev->>API: POST /api/v1/file/{uuid}/face_trace/sortby<br/>{ "sort_by": "face_count", "limit": 3 }
+    Dev->>API: POST /api/v1/file/{file_uuid}/face_trace/sortby<br/>{ "sort_by": "face_count", "limit": 3 }
    API-->>Dev: { "total_traces": 6892, "traces": [...] }
-    Dev->>API: GET /api/v1/file/{uuid}/trace/3128/video
+    Dev->>API: GET /api/v1/file/{file_uuid}/trace/3128/video
    API-->>Dev: MP4 binary
    Note over Dev: Browser opens video with bbox
 ```
@@ -213,6 +213,6 @@ sequenceDiagram
 |------|------|
 | 登入取得 Key | `curl -X POST https://api.momentry.ddns.net/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"demo","password":"demo"}'` |
 | 列出檔案 | `curl https://api.momentry.ddns.net/api/v1/files -H "X-API-Key: muser_test_001"` |
-| Top Traces | `curl -X POST https://api.momentry.ddns.net/api/v1/file/{uuid}/face_trace/sortby -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" -d '{"sort_by":"face_count","limit":3}'` |
-| BM25 搜尋 | `curl -X POST https://api.momentry.ddns.net/api/v1/search/universal -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" -d '{"query":"friends","mode":"bm25","uuid":"{uuid}"}'` |
+| Top Traces | `curl -X POST https://api.momentry.ddns.net/api/v1/file/{file_uuid}/face_trace/sortby -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" -d '{"sort_by":"face_count","limit":3}'` |
+| BM25 搜尋 | `curl -X POST https://api.momentry.ddns.net/api/v1/search/universal -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" -d '{"query":"friends","mode":"bm25","uuid":"{file_uuid}"}'` |
 | 身分列表 | `curl https://api.momentry.ddns.net/api/v1/identities?page=1&page_size=5 -H "X-API-Key: muser_test_001"` |
--- a/docs_v1.0/API_V1.0.0/DEMO_SCRIPT_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/DEMO_SCRIPT_V1.0.0.md
@@ -106,7 +106,7 @@ https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"friends","limit":3,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 **預期**: `"You won't find it difficult to make some new friends."` score=0.90
@@ -116,7 +116,7 @@ curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"name","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"name","limit":3,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 **預期**: `"What's your name?"` score=0.90
@@ -154,7 +154,7 @@ curl "$BASE/api/v1/faces/candidates?page=1&page_size=3" -H "$KEY"
 ```bash
 curl -X POST $BASE/api/v1/search/smart -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"Audrey Hepburn","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"Audrey Hepburn","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 ---
--- a/docs_v1.0/API_V1.0.0/DEMO_SCRIPT_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/DEMO_SCRIPT_v1.0.0.md
@@ -106,7 +106,7 @@ https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"friends","limit":3,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 **預期**: `"You won't find it difficult to make some new friends."` score=0.90
@@ -116,7 +116,7 @@ curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"name","limit":3,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"name","limit":3,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 **預期**: `"What's your name?"` score=0.90
@@ -154,7 +154,7 @@ curl "$BASE/api/v1/faces/candidates?page=1&page_size=3" -H "$KEY"
 ```bash
 curl -X POST $BASE/api/v1/search/smart -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"Audrey Hepburn","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+  -d '{"query":"Audrey Hepburn","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```

 ---
--- a/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_V1.0.0.md
@@ -49,7 +49,7 @@ curl "$BASE/api/v1/file/$FILE/trace/2/faces?limit=3&interpolate=true" -H "$KEY"

 Curl:
 ```bash
-curl -X POST $BASE/api/v1/search/universal -H "$KEY" -H "Content-Type: application/json" -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"$FILE"}'
+curl -X POST $BASE/api/v1/search/universal -H "$KEY" -H "Content-Type: application/json" -d '{"query":"friends","limit":3,"mode":"bm25","file_uuid":"$FILE"}'
 ```

 **預期**: "You won't find it difficult to make some new friends."
--- a/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md
@@ -49,7 +49,7 @@ curl "$BASE/api/v1/file/$FILE/trace/2/faces?limit=3&interpolate=true" -H "$KEY"

 Curl:
 ```bash
-curl -X POST $BASE/api/v1/search/universal -H "$KEY" -H "Content-Type: application/json" -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"$FILE"}'
+curl -X POST $BASE/api/v1/search/universal -H "$KEY" -H "Content-Type: application/json" -d '{"query":"friends","limit":3,"mode":"bm25","file_uuid":"$FILE"}'
 ```

 **預期**: "You won't find it difficult to make some new friends."
--- a/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md
@@ -220,8 +220,8 @@ MP4 video segment with face bboxes.

 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
-| `start` | int | — | Start frame (required) |
-| `end` | int | — | End frame (required) |
+| `start_frame` | int | — | Start frame (required) |
+| `end_frame` | int | — | End frame (required) |
 | `duration` | float | 10 | Clip duration seconds |

 ---
@@ -258,7 +258,7 @@ Auth: X-API-Key: muser_test_apikey
 | 7 | `GET /trace/1271/faces` | `?limit=2` | 33 total, paginated |
 | 8 | `GET /trace/1271/faces` | `?limit=10&interpolate=true` | 271 frames |
 | 9 | `GET /trace/2/video` | — | 2.0MB MP4 |
-| 10 | `GET /video/bbox` | `?start=4650&end=4680` | 1.9MB MP4 overlay |
+| 10 | `GET /video/bbox` | `?start_frame=4650&end_frame=4680` | 1.9MB MP4 overlay |
 | 11 | `GET /thumbnail` | `?frame=4650` | 82KB JPEG |

 ---
--- a/docs_v1.0/API_V1.0.0/VISION_AGENT_API_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/VISION_AGENT_API_V1.0.0.md
@@ -72,7 +72,7 @@ curl localhost:3003/api/v1/agents/vision/detect \

 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
-| `uuid` | string | `aeed71342a...` | Video file UUID |
+| `file_uuid` | string | `aeed71342a...` | Video file UUID |
 | `frame` | int | `0` | **Precise** frame number |
 | `time` | float | — | **Compatibility** seconds (auto-converted) |
 | `query` | string | `"find the gun"` | Natural language query (parsed to extract object) |