docs: add real curl examples with verified responses

docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md

@@ -10,7 +10,7 @@ owner: "Warren"
 
 # Momentry Core API Reference v1.0.0
 
-56 endpoints across 10 categories.
+56 endpoints across 10 categories, with real curl examples and responses.
 
 ## Base
 
@@ -20,6 +20,8 @@ owner: "Warren"
 | Development | `http://localhost:3003` |
 | Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |
 
+---
+
 ## 1. System
 
 | # | Method | Path | Description |
@@ -33,11 +35,14 @@ owner: "Warren"
 | 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
 | 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
 
-**Example:**
 ```bash
-GET /health
+curl http://localhost:3002/health
-→ {"status":"ok","version":"1.0.0","uptime_ms":248233}
 ```
+```json
+{"status":"ok","version":"1.0.0","uptime_ms":7052517}
+```
+
+---
 
 ## 2. File Management
 
@@ -54,12 +59,25 @@ GET /health
 | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
 | 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
 
-**Example:**
 ```bash
-POST /api/v1/files/register
+curl -X POST http://localhost:3002/api/v1/files/register \
-{"file_path":"/sftpgo/data/demo/video.mp4"}
+  -H "X-API-Key: muser_test_apikey" \
-→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0}
+  -H "Content-Type: application/json" \
+  -d '{"file_path":"/sftpgo/data/demo/video.mp4"}'
 ```
+```json
+{"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0}
+```
+
+```bash
+curl "http://localhost:3002/api/v1/files?page=1&page_size=2" \
+  -H "X-API-Key: muser_test_apikey"
+```
+```json
+{"files":[{"file_name":"Charade (1963)..."},{"file_name":"view13.mp4"}],"total":37}
+```
+
+---
 
 ## 3. Search
 
@@ -74,12 +92,27 @@ POST /api/v1/files/register
 | 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
 | 26 | POST | `/api/v1/search/frames` | Frame-level search |
 
-**Example:**
 ```bash
-POST /api/v1/search/universal
+curl -X POST http://localhost:3002/api/v1/search/universal \
-{"query":"friends","mode":"bm25","file_uuid":"3abeee81..."}
+  -H "X-API-Key: muser_test_apikey" \
-→ {"count":1,"results":[{"text":"You won't find it difficult..."}]}
+  -H "Content-Type: application/json" \
+  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
 ```
+```json
+{"count":1,"results":[{"text":"What's your name?","score":0.90}]}
+```
+
+```bash
+curl -X POST http://localhost:3002/api/v1/search/universal \
+  -H "X-API-Key: muser_test_apikey" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"friends","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
+```
+```json
+{"count":1,"results":[{"text":"You won't find it difficult to make some new friends.","score":0.90}]}
+```
+
+---
 
 ## 4. Face Trace
 
@@ -88,18 +121,43 @@ POST /api/v1/search/universal
 | 27 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) |
 | 28 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |
 
-**Parameters:**
+### sortby — list traces
+
+Parameters:
 - `sort_by`: `face_count` | `duration` | `first_appearance`
 - `min_faces`, `min_confidence`, `max_confidence`: filters
-- `interpolate=true`: fills sparse gaps with lerp bbox
+- `limit`: max results
 
-**Example:**
 ```bash
-POST /api/v1/file/3abeee81.../face_trace/sortby
+curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby" \
-{"sort_by":"face_count","limit":3}
+  -H "X-API-Key: muser_test_apikey" \
-→ {"total_traces":6892,"total_faces":108204,
+  -H "Content-Type: application/json" \
-   "traces":[{"trace_id":3128,"face_count":1109}]}
+  -d '{"sort_by":"face_count","limit":2}'
 ```
+```json
+{"success":true,"total_traces":6892,"total_faces":108204,"traces":[
+  {"trace_id":3128,"face_count":1109,"avg_confidence":0.779},
+  {"trace_id":3126,"face_count":743,"avg_confidence":0.758}
+]}
+```
+
+### trace/:trace_id/faces — individual detections
+
+Parameters:
+- `limit`, `offset`: pagination
+- `interpolate`: boolean (fills sparse gaps with lerp bbox)
+
+```bash
+curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/faces?limit=2&interpolate=true" \
+  -H "X-API-Key: muser_test_apikey"
+```
+```json
+{"success":true,"trace_id":2,"total":1,"faces":[
+  {"id":12399,"start_frame":4620,"start_time":184.8,"x":787,"y":582,"width":225,"height":225,"confidence":0.666,"interpolated":false}
+]}
+```
+
+---
 
 ## 5. Media
 
@@ -110,6 +168,20 @@ POST /api/v1/file/3abeee81.../face_trace/sortby
 | 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=) |
 
+```bash
+curl -o thumb.jpg "http://localhost:3002/api/v1/file/3abeee81.../thumbnail?frame=4650" \
+  -H "X-API-Key: muser_test_apikey"
+```
+Returns JPEG binary (82KB, 1920×1080).
+
+```bash
+curl -o trace_clip.mp4 "http://localhost:3002/api/v1/file/3abeee81.../trace/2/video" \
+  -H "X-API-Key: muser_test_apikey"
+```
+Returns MP4 video binary (3.0MB) with bbox overlay.
+
+---
+
 ## 6. Identities
 
 | # | Method | Path | Description |
@@ -123,11 +195,27 @@ POST /api/v1/file/3abeee81.../face_trace/sortby
 | 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
 | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
 
-**Example:**
 ```bash
-GET /api/v1/identities?page=1&page_size=5
+curl "http://localhost:3002/api/v1/identities?page=1&page_size=3" \
-→ {"identities":[{"name":"Cary Grant","tmdb_id":...}]}
+  -H "X-API-Key: muser_test_apikey"
 ```
+```json
+{"identities":[
+  {"name":"Cary Grant","tmdb_id":2102},
+  {"name":"Audrey Hepburn","tmdb_id":187},
+  {"name":"Walter Matthau","tmdb_id":2091}
+]}
+```
+
+```bash
+curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2" \
+  -H "X-API-Key: muser_test_apikey"
+```
+```json
+{"total":42,"candidates":[{"frame_number":30,"confidence":0.85},...]}
+```
+
+---
 
 ## 7. Identity Binding
 
@@ -137,12 +225,17 @@ GET /api/v1/identities?page=1&page_size=5
 | 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
 | 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities |
 
-**Example:**
 ```bash
-POST /api/v1/identity/a9a90105.../bind
+curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind" \
-{"file_uuid":"3abeee81...","face_id":"face_42"}
+  -H "X-API-Key: muser_test_apikey" \
-→ {"success":true}
+  -H "Content-Type: application/json" \
+  -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'
 ```
+```json
+{"success":true}
+```
+
+---
 
 ## 8. Resources
 
@@ -152,6 +245,16 @@ POST /api/v1/identity/a9a90105.../bind
 | 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
 | 46 | GET | `/api/v1/resources` | List all resources |
 
+```bash
+curl "http://localhost:3002/api/v1/resources" \
+  -H "X-API-Key: muser_test_apikey"
+```
+```json
+{"resources":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}]}
+```
+
+---
+
 ## 9. Agents — 5W1H
 
 | # | Method | Path | Description |
@@ -161,6 +264,18 @@ POST /api/v1/identity/a9a90105.../bind
 | 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
 | 50 | GET | `/api/v1/agents/5w1h/status` | Job status |
 
+```bash
+curl -X POST "http://localhost:3002/api/v1/agents/translate" \
+  -H "X-API-Key: muser_test_apikey" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"Hello world","target_language":"zh-TW"}'
+```
+```json
+{"success":true,"translated_text":"你好世界"}
+```
+
+---
+
 ## 10. Agents — Identity
 
 | # | Method | Path | Description |