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

docs: sync case-insensitive variant

Browse Source
This commit is contained in:
Accusys
2026-05-25 10:31:37 +08:00
parent b9e93c6293
commit 20dae387ee
1 changed files with 66 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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