From 2e9bb6e52bf6ec38ff236449405480b130b47f14 Mon Sep 17 00:00:00 2001 From: Accusys Date: Thu, 14 May 2026 17:14:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20update=20API=20reference=20to=20V4.1=20?= =?UTF-8?q?=E2=80=94=20health=20pipeline,=20trace=20debug,=20identity=20se?= =?UTF-8?q?arch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md | 87 +++++++++++++++++--- 1 file changed, 76 insertions(+), 11 deletions(-) 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 1a2bbb2..8d9e9ed 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-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} + } +} ``` --- @@ -164,17 +209,29 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2 | 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=) | +| 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/{uuid}/trace/42/video?mode=normal" +# Debug mode +curl -o trace_debug.mp4 "http://localhost:3002/api/v1/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 +247,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=&uuid=` | Full-text search → identity chunks | ```bash curl "http://localhost:3002/api/v1/identities?page=1&page_size=3" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" @@ -275,8 +334,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