diff --git 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 index 11d6d61..6343be6 100644 --- 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-14" -version: "V4.1" +date: "2026-05-25" +version: "V4.2" status: "active" owner: "Warren" --- # Momentry Core API Reference v1.0.0 -58 endpoints across 10 categories, with real curl examples and responses. +55 endpoints across 10 categories, with real curl examples and responses. ## Base @@ -30,12 +30,13 @@ owner: "Warren" |---|--------|------|-------------| | 1 | GET | `/health` | Server status (ok/degraded) | | 2 | GET | `/health/detailed` | Per-service health + latency | -| 3 | POST | `/api/v1/auth/login` | Username/password → API key | -| 4 | POST | `/api/v1/auth/logout` | Invalidate session | -| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | +| 3 | GET | `/health/consistency` | Data consistency check | +| 4 | POST | `/api/v1/auth/login` | Username/password → API key | +| 5 | POST | `/api/v1/auth/logout` | Invalidate session | | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status | -| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health | -| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache | +| 7 | POST | `/api/v1/config/cache` | Toggle Redis cache | +| 8 | POST | `/api/v1/config/auto-pipeline` | Toggle auto-pipeline on register | +| 9 | POST | `/api/v1/config/watcher-auto-register` | Toggle watcher auto-register | ```bash curl http://localhost:3002/health @@ -44,8 +45,8 @@ curl http://localhost:3002/health { "status": "ok", "version": "1.0.0", - "build_git_hash": "26f2434", - "build_timestamp": "2026-05-14T09:09:17Z", + "build_git_hash": "de88fd4e", + "build_timestamp": "2026-05-25", "uptime_ms": 7052517 } ``` @@ -68,8 +69,8 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com ```json { "status": "ok", - "build_git_hash": "26f2434", - "build_timestamp": "2026-05-14T09:09:17Z", + "build_git_hash": "de88fd4e", + "build_timestamp": "2026-05-25", "services": { "postgres": {"status": "ok", "latency_ms": 6}, "redis": {"status": "ok", "latency_ms": 0}, @@ -103,17 +104,17 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com | # | Method | Path | Description | |---|--------|------|-------------| -| 9 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` | -| 10 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename | -| 11 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) | -| 12 | GET | `/api/v1/files/scan` | Scan directory for new files | -| 13 | GET | `/api/v1/files` | List files (paginated) | -| 14 | GET | `/api/v1/file/:file_uuid` | Single file detail | -| 15 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | -| 16 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | -| 17 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) | -| 18 | GET | `/api/v1/progress/:file_uuid` | Processing progress | -| 19 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | +| 10 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` | +| 11 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename | +| 12 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) | +| 13 | GET | `/api/v1/files/scan` | Scan directory for new files | +| 14 | GET | `/api/v1/files` | List files (paginated) | +| 15 | GET | `/api/v1/file/:file_uuid` | Single file detail | +| 16 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | +| 17 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | +| 18 | POST | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) | +| 19 | POST | `/api/v1/progress/:file_uuid` | Processing progress | +| 20 | POST | `/api/v1/jobs` | Monitor jobs (filterable) | ```bash curl -X POST http://localhost:3002/api/v1/files/register -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}' @@ -154,14 +155,14 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse | # | Method | Path | Description | |---|--------|------|-------------| -| 20 | POST | `/api/v1/search/visual` | Visual chunk search | -| 21 | POST | `/api/v1/search/visual/class` | By object class | -| 22 | POST | `/api/v1/search/visual/density` | By spatial density | -| 23 | POST | `/api/v1/search/visual/combination` | Combined visual search | -| 24 | POST | `/api/v1/search/visual/stats` | Visual stats | -| 25 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | -| 26 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) | -| 27 | POST | `/api/v1/search/frames` | Frame-level search | +| 21 | POST | `/api/v1/search/visual` | Visual chunk search | +| 22 | POST | `/api/v1/search/visual/class` | By object class | +| 23 | POST | `/api/v1/search/visual/density` | By spatial density | +| 24 | POST | `/api/v1/search/visual/combination` | Combined visual search | +| 25 | POST | `/api/v1/search/visual/stats` | Visual stats | +| 26 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | +| 27 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) | +| 28 | POST | `/api/v1/search/frames` | Frame-level search | ```bash curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}' @@ -183,10 +184,10 @@ curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser | # | Method | Path | Description | |---|--------|------|-------------| -| 28 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) | -| 29 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) | +| 29 | POST | `/api/v1/file/:file_uuid/traces` | List traces (sorted/filtered) | +| 30 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) | -### sortby — list traces +### traces — list traces Parameters: - `sort_by`: `face_count` | `duration` | `first_appearance` @@ -194,7 +195,7 @@ Parameters: - `limit`: max results ```bash -curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"sort_by":"face_count","limit":2}' +curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/traces" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"sort_by":"face_count","limit":2}' ``` ```json {"success":true,"total_traces":6892,"total_faces":108204,"traces":[ @@ -224,10 +225,10 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2 | # | Method | Path | Description | |---|--------|------|-------------| -| 30 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) | -| 31 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). | -| 32 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. | -| 33 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) | +| 31 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) | +| 32 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). | +| 33 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. | +| 34 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) | All video endpoints support: - `mode=normal|debug` (default: `normal`) @@ -260,16 +261,16 @@ Green bbox per face detection: actual frames `thickness=4`, interpolated `thickn | # | Method | Path | Description | |---|--------|------|-------------| -| 33 | GET | `/api/v1/identities` | List all identities | -| 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file | -| 35 | POST | `/api/v1/identity` | Register new identity | -| 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail | -| 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity | -| 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 | +| 35 | GET | `/api/v1/identities` | List all identities | +| 36 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file | +| 37 | POST | `/api/v1/identity` | Register new identity | +| 38 | GET | `/api/v1/identity/:identity_uuid` | Identity detail | +| 39 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity | +| 40 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity | +| 41 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity | +| 42 | GET | `/api/v1/faces/candidates` | Unbound face gallery | +| 43 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks | +| 44 | 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" @@ -307,9 +308,9 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2" -H "X-A | # | Method | Path | Description | |---|--------|------|-------------| -| 43 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | -| 44 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | -| 45 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity | +| 45 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | +| 46 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | +| 47 | 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"}' @@ -324,9 +325,9 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c | # | Method | Path | Description | |---|--------|------|-------------| -| 46 | POST | `/api/v1/resource/register` | Register processing resource | -| 47 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | -| 48 | GET | `/api/v1/resources` | List all resources | +| 48 | POST | `/api/v1/resource/register` | Register processing resource | +| 49 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | +| 50 | GET | `/api/v1/resources` | List all resources | ```bash curl "http://localhost:3002/api/v1/resources" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" @@ -341,10 +342,10 @@ curl "http://localhost:3002/api/v1/resources" -H "X-API-Key: muser_686008560363 | # | Method | Path | Description | |---|--------|------|-------------| -| 49 | POST | `/api/v1/agents/translate` | AI text translation | -| 50 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | -| 51 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | -| 52 | GET | `/api/v1/agents/5w1h/status` | Job status | +| 51 | POST | `/api/v1/agents/translate` | AI text translation | +| 52 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | +| 53 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | +| 54 | GET | `/api/v1/agents/5w1h/status` | Job status | ```bash curl -X POST "http://localhost:3002/api/v1/agents/translate" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"text":"Hello world","target_language":"zh-TW"}' @@ -359,11 +360,10 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate" -H "X-API-Key: mus | # | Method | Path | Description | |---|--------|------|-------------| -| 53 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | -| 54 | GET | `/api/v1/agents/identity/status` | Analysis status | -| 55 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | -| 56 | POST | `/api/v1/agents/suggest/merge` | Suggest merge | -| 57 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | +| 55 | POST | `/api/v1/agents/identity/match-from-photo` | Match face from photo | +| 56 | POST | `/api/v1/agents/identity/match-from-trace` | Match face from trace | +| 57 | POST | `/api/v1/agents/suggest/merge` | Suggest merge | +| 58 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | --- @@ -371,10 +371,11 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate" -H "X-API-Key: mus | Version | Date | Changes | |---------|------|---------| +| V4.2 | 2026-05-25 | Removed phantom routes (stats/ingest, stats/inference, agents/identity/status); fixed HTTP methods (chunk, progress, jobs → POST); renamed endpoints (face_trace/sortby → traces, analyze → match-from-photo, suggest → match-from-trace); added config endpoints (consistency, auto-pipeline, watcher-auto-register); updated git hash to de88fd4e | | 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 (58 endpoints) +- `API_DICTIONARY_V1.0.0.md` — Quick reference (55 endpoints) - `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples - `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference