admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update API reference to V4.1 — health pipeline, trace debug, identity search

Browse Source
This commit is contained in:
Accusys
2026-05-14 17:14:33 +08:00
parent 26f243428d
commit 2e9bb6e52b
1 changed files with 76 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
View File

@@ -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