momentry_core/docs_v1.0/API_DOCUMENTATION.md

Momentry Core API Documentation v1.0.0

Overview

Momentry Core is a digital asset management system with video analysis, RAG, and face recognition capabilities. This document covers all API endpoints available in v1.0.0.

Base URL: http://<host>:<port>

• Production: Port 3002
• Development (Playground): Port 3003

Authentication: All protected routes require API key validation via X-API-Key header.

---

API Classification

The API is organized into 7 categories:

Category	Prefix	Description
Health & Auth	/health, /api/v1/auth	System health, authentication
Asset Management	/api/v1/register, /api/v1/files, /api/v1/assets	File registration, probing, processing
Search	/api/v1/search, /api/v1/n8n	Text, hybrid, visual, and n8n search
Video Details	/api/v1/videos, /api/v1/progress	Video listing, details, chunks
Identity & Binding	/api/v1/identities, /api/v1/signals	Face/speaker identity management
Jobs & Rules	/api/v1/jobs, /api/v1/rules	Processing job monitoring
Stats & Config	/api/v1/stats, /api/v1/config	System statistics, configuration

---

1. Health & Authentication

GET /health

Basic health check.

Response:

{
  "status": "ok",
  "version": "v1.0.0",
  "uptime_ms": 12345
}

GET /health/detailed

Detailed health check with service status (PostgreSQL, Redis, Qdrant, MongoDB).

Response:

{
  "status": "ok",
  "version": "v1.0.0",
  "uptime_ms": 12345,
  "services": {
    "postgres": { "status": "ok", "latency_ms": 5 },
    "redis": { "status": "ok", "latency_ms": 2 },
    "qdrant": { "status": "ok", "latency_ms": 10 },
    "mongodb": { "status": "ok", "latency_ms": 8 }
  }
}

POST /api/v1/auth/login

Authenticate and obtain API key.

Request:

{
  "username": "demo",
  "password": "demo"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "api_key": "muser_test_001",
  "user": { "username": "demo" }
}

POST /api/v1/auth/logout

Logout session.

Response:

{ "success": true }

---

2. Asset Management

POST /api/v1/register

Register a video file (legacy path-based).

Request:

{ "path": "./demo/video.mp4" }

Response:

{
  "file_uuid": "384b0ff44aaaa1f1",
  "file_id": 1,
  "job_id": 1,
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "already_exists": false
}

POST /api/v1/files/register

Register a file with full metadata (recommended). Supports move detection.

Request:

{
  "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
  "user_id": null
}

Response:

{
  "success": true,
  "file_uuid": "384b0ff44aaaa1f1",
  "file_name": "video.mp4",
  "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4",
  "file_type": "video",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30.0,
  "total_frames": 3615,
  "registration_time": null,
  "already_exists": false,
  "message": "File registered successfully"
}

GET /api/v1/files/scan

Scan filesystem for unregistered files.

POST /api/v1/unregister

Unregister a video file.

Request:

{ "uuid": "384b0ff44aaaa1f1" }

POST /api/v1/probe

Probe a video file for metadata.

Request:

{ "path": "./demo/video.mp4" }

Response:

{
  "uuid": "384b0ff44aaaa1f1",
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30.0,
  "cached": true,
  "format": { ... },
  "streams": [ ... ]
}

GET /api/v1/assets/:uuid/probe

Probe a video by UUID.

POST /api/v1/assets/:uuid/process

Trigger processing pipeline for an asset.

Request:

{
  "processors": ["asr", "cut", "yolo", "ocr", "face", "pose", "asrx", "visual_chunk"]
}

Response:

{
  "job_id": 1,
  "asset_uuid": "384b0ff44aaaa1f1",
  "status": "PENDING",
  "message": "Processing triggered for video.mp4"
}

GET /api/v1/assets/:uuid/status

Get asset processing status with frame progress.

Response:

{
  "uuid": "384b0ff44aaaa1f1",
  "file_name": "video.mp4",
  "registration_time": "2026-04-30T10:00:00Z",
  "processing_status": "processing",
  "current_job_id": "abc-123",
  "frame_progress": {
    "total_frames": 3615,
    "processed_frames": 1200,
    "progress_percent": 33.2
  }
}

---

3. Search

POST /api/v1/search

Vector/smart search across chunks.

Request:

{
  "query": "person talking about AI",
  "mode": "smart",
  "uuid": "384b0ff44aaaa1f1",
  "limit": 10
}

Response:

{
  "results": [
    {
      "uuid": "384b0ff44aaaa1f1",
      "chunk_id": "chunk_1",
      "chunk_type": "sentence",
      "start_time": 10.5,
      "end_time": 15.2,
      "text": "AI is transforming...",
      "score": 0.85
    }
  ],
  "query": "person talking about AI"
}

POST /api/v1/search/hybrid

Hybrid search (vector + BM25).

Request:

{
  "query": "search term",
  "limit": 10,
  "uuid": "384b0ff44aaaa1f1",
  "vector_weight": 0.7,
  "bm25_weight": 0.3
}

POST /api/v1/search/bm25

BM25 full-text search.

POST /api/v1/search/visual

Search visual chunks by criteria.

Request:

{
  "uuid": "384b0ff44aaaa1f1",
  "criteria": {
    "object_class": "person",
    "min_count": 1
  }
}

POST /api/v1/search/visual/class

Search by object class.

Request:

{
  "uuid": "384b0ff44aaaa1f1",
  "object_class": "person",
  "min_count": 1,
  "max_count": null
}

POST /api/v1/search/visual/density

Search by object density.

Request:

{
  "uuid": "384b0ff44aaaa1f1",
  "min_density": 0.5,
  "max_density": null
}

POST /api/v1/search/visual/combination

Search by object combination.

Request:

{
  "uuid": "384b0ff44aaaa1f1",
  "combination": [["person", 2], ["car", 1]]
}

POST /api/v1/search/visual/stats

Get visual chunk statistics.

Request:

{ "uuid": "384b0ff44aaaa1f1" }

POST /api/v1/n8n/search

Search via n8n integration.

POST /api/v1/n8n/search/bm25

BM25 search via n8n.

POST /api/v1/n8n/search/hybrid

Hybrid search via n8n.

POST /api/v1/n8n/search/smart

Smart search via n8n.

---

4. Video Details

GET /api/v1/videos

List all registered videos with pagination.

Query Parameters:

• page: Page number (default: 1)
• page_size: Items per page (default: 20)
• status: Filter by status
• q: Search query
• uuid: Filter by UUID

Response:

{
  "files": [
    {
      "file_uuid": "384b0ff44aaaa1f1",
      "file_path": "/path/to/video.mp4",
      "file_name": "video.mp4",
      "file_type": "video",
      "duration": 120.5,
      "width": 1920,
      "height": 1080,
      "status": "completed",
      "created_at": "2026-04-30T10:00:00Z",
      "file_size": 52428800,
      "total_frames": 3615
    }
  ],
  "count": 1,
  "page": 1,
  "page_size": 20
}

DELETE /api/v1/videos/:uuid

Delete a video and all associated data (faces, chunks, processor results).

Response:

{
  "success": true,
  "message": "File 384b0ff44aaaa1f1 unregistered successfully...",
  "file_uuid": "384b0ff44aaaa1f1",
  "deleted_face_detections": 150,
  "deleted_processor_results": 8,
  "deleted_chunks": 45
}

GET /api/v1/videos/:uuid/details

Get detailed chunk information.

Query Parameters:

• chunk_id: Specific chunk ID (required)
• parent_id: Parent chunk ID

Response:

{
  "uuid": "384b0ff44aaaa1f1",
  "chunk_id": "chunk_1",
  "chunk_type": "sentence",
  "frame_range": {
    "start_frame": 315,
    "end_frame": 456,
    "duration_frames": 141,
    "fps": 30.0
  },
  "reference_time": {
    "start": 10.5,
    "end": 15.2
  },
  "text_content": "AI is transforming...",
  "summary_text": "Discussion about AI impact",
  "speaker_ids": ["SPEAKER_0"],
  "person_ids": ["face_100"]
}

GET /api/v1/videos/:uuid/pre_chunks

List pre-processor chunks.

Query Parameters:

• processor_type: Filter by processor (asr, yolo, face, etc.)
• page: Page number
• page_size: Items per page

GET /api/v1/progress/:uuid

Get processing progress for a video.

---

5. Identity & Binding

POST /api/v1/identities/from-face

Register a global identity from face.json with multi-angle reference vectors.

Request:

{
  "face_json_path": "/path/to/face.json",
  "identity_name": "John Doe",
  "schema": "dev"
}

POST /api/v1/identities/from-person

Register identity from a person in a video.

Request:

{
  "file_uuid": "384b0ff44aaaa1f1",
  "person_id": "person_1",
  "identity_name": "John Doe"
}

GET /api/v1/identities

List all global identities.

Query Parameters:

• page: Page number
• page_size: Items per page

GET /api/v1/faces/candidates

List unbound face candidates.

Query Parameters:

• file_uuid: Filter by file
• min_confidence: Minimum confidence (default: 0.5)
• page, page_size: Pagination

GET /api/v1/identities/:identity_id/faces

Get all faces for an identity.

GET /api/v1/faces/:face_id/thumbnail

Get face thumbnail image (JPEG).

POST /api/v1/identities/bind

Bind a face/speaker to an identity.

Request:

{
  "identity_id": 1,
  "binding_type": "face",
  "binding_value": "face_100",
  "source": "manual"
}

POST /api/v1/identities/unbind

Unbind an identity.

Request:

{
  "binding_type": "face",
  "binding_value": "face_100"
}

GET /api/v1/identity/:binding_type/:binding_value

Get identity info by binding.

GET /api/v1/signals/unbound

List unbound signals.

Query Parameters:

• uuid: File UUID
• binding_type: "face" or "speaker"

GET /api/v1/signals/:uuid/:binding_type/:binding_value/timeline

Get signal timeline (all chunks for a face/speaker).

POST /api/v1/identities/suggest-av

Suggest audio-visual bindings based on temporal overlap.

Request:

{
  "file_uuid": "384b0ff44aaaa1f1",
  "overlap_threshold": 0.6
}

---

6. Jobs & Rules

GET /api/v1/jobs

List all monitor jobs.

Query Parameters:

• page, page_size: Pagination
• status: Filter by status

GET /api/v1/jobs/:job_id

Get job details with processor information.

Response:

{
  "job_id": "1",
  "asset_uuid": "384b0ff44aaaa1f1",
  "rule": "default",
  "status": "RUNNING",
  "current_processor_id": "asr",
  "frame_progress": {
    "total_frames": 3615,
    "processed_frames": 1200,
    "progress_percent": 33.2
  }
}

GET /api/v1/rules/:rule/status

Get rule status with active jobs.

---

7. Stats & Configuration

GET /api/v1/stats/ingest

Get ingestion statistics.

Response:

{
  "total_videos": 50,
  "total_chunks": 1200,
  "sentence_chunks": 800,
  "cut_chunks": 300,
  "time_chunks": 100,
  "searchable_chunks": 1150,
  "chunks_with_visual": 450,
  "chunks_with_summary": 200,
  "pending_videos": 5
}

GET /api/v1/stats/sftpgo

Get SFTPGo status and registered videos.

GET /api/v1/stats/inference

Check inference engine health (Ollama, llama-server).

Response:

{
  "ollama": {
    "engine": "Ollama",
    "model": "nomic-embed-text",
    "status": "ok",
    "latency_ms": 15
  },
  "llama_server": {
    "engine": "llama-server",
    "model": "gemma4_e4b_q5",
    "status": "ok",
    "latency_ms": 25
  }
}

POST /api/v1/config/cache

Toggle MongoDB cache.

Request:

{ "enabled": false }

Response:

{
  "success": true,
  "cache_enabled": false,
  "message": "Cache disabled"
}

---

API Usage Patterns

1. List Pattern

GET /api/v1/videos?page=1&page_size=20

• Supports pagination
• Optional filters via query parameters
• Returns { items: [...], count, page, page_size }

2. Detail Pattern

GET /api/v1/videos/:uuid/details?chunk_id=chunk_1

• Path parameter for resource identifier
• Query parameters for sub-resource selection
• Returns detailed object with nested structures

3. Operation Pattern

POST /api/v1/assets/:uuid/process

• Action-oriented endpoint
• Request body contains operation parameters
• Returns operation status and job ID

4. Application Pattern

POST /api/v1/identities/bind
POST /api/v1/identities/suggest-av

• Complex workflows with multiple steps
• Often involve external services (Python scripts, FFmpeg)
• Return comprehensive results with metadata

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn't exist
500	Internal Server Error - Database/service failure

---

V4.0 Architecture Notes

Key Changes from V3.x

• video_uuid → file_uuid (terminology update)
• person_identities table removed
• Face → Identity direct binding (no intermediate person_id)
• 28 person_id APIs removed (except register/bind)
• Chunk binding auto via time alignment

Identity Model

Face Detection → Identity (direct binding)
Speaker Detection → Identity (direct binding)

Processing Pipeline

Register → Probe → ASR → CUT → YOLO → OCR → Face → Pose → ASRX → Visual Chunk