04 Lookup - Momentry API Docs

File Lookup

`GET /api/v1/files/lookup`

Auth: Required Scope: file-level

Search registered files by file name. Performs a case-insensitive LIKE search on the file name column. Returns basic info about matching files.

Query Parameters

Field	Type	Required	Description
`file_name`	string	Yes	File name to search for (partial matches supported)

Example

# Look up a specific file
curl -s "$API/api/v1/files/lookup?file_name=video.mp4" \
  -H "X-API-Key: $KEY"

# Partial name search
curl -s "$API/api/v1/files/lookup?file_name=charade" \
  -H "X-API-Key: $KEY" | jq '.matches[].file_name'

Response (200)

{
  "file_name": "video.mp4",
  "exists": true,
  "matches": [
    {
      "file_uuid": "a03485a40b2df2d3",
      "file_name": "video.mp4",
      "file_type": "video",
      "status": "completed"
    }
  ],
  "next_name": "video (2).mp4"
}

Field	Type	Description
`file_name`	string	Searched name
`exists`	boolean	Exact name match exists
`matches`	array	Array of matching registered files
`matches[].file_uuid`	string	32-char hex UUID
`matches[].file_name`	string	Registered file name
`matches[].file_type`	string	`"video"`, `"audio"`, or `null`
`matches[].status`	string	Registration/processing status
`next_name`	string	Suggested name for avoiding conflicts

File Listing

`GET /api/v1/files`

Auth: Required Scope: system-level

List all registered files with pagination. Optionally filter by status or fetch a specific file by UUID.

Query Parameters

Field	Type	Required	Default	Description
`page`	integer	No	1	Page number
`page_size`	integer	No	20	Items per page
`status`	string	No	—	Filter by status: `registered`, `processing`, `completed`, `failed`, `indexed`, `checked_out`
`file_uuid`	string	No	—	Fetch a specific file (returns as single-item list)

Example

# List all files (paginated)
curl -s "$API/api/v1/files?page=1&page_size=10" \
  -H "X-API-Key: $KEY"

# Filter by status
curl -s "$API/api/v1/files?status=completed" \
  -H "X-API-Key: $KEY"

# Fetch specific file
curl -s "$API/api/v1/files?file_uuid=$FILE_UUID" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "total": 42,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
      "file_name": "video.mp4",
      "file_path": "/path/to/video.mp4",
      "status": "completed"
    }
  ]
}

Field	Type	Description
`success`	boolean	Always true on 200
`total`	integer	Total file count
`page`	integer	Current page
`page_size`	integer	Items per page
`data`	array	Array of file items
`data[].file_uuid`	string	32-char hex UUID
`data[].file_name`	string	Registered file name
`data[].file_path`	string	Full filesystem path
`data[].status`	string	Processing status

`GET /api/v1/file/:file_uuid`

Auth: Required Scope: file-level

Get detailed info for a specific registered file including metadata, duration, FPS, and probe data.

Example

curl -s "$API/api/v1/file/$FILE_UUID" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "file_name": "video.mp4",
  "file_path": "/path/to/video.mp4",
  "status": "completed",
  "duration": 120.5,
  "fps": 24.0,
  "metadata": {
    "format": {"duration": "120.5", "size": "794863677"},
    "streams": [{"codec_name": "h264", "width": 1920, "height": 1080}]
  },
  "created_at": "2026-05-16T12:00:00Z"
}

Field	Type	Description
`success`	boolean	Always true on 200
`file_uuid`	string	32-char hex UUID
`file_name`	string	Registered file name
`file_path`	string	Full filesystem path
`status`	string	Processing status
`duration`	float	Duration in seconds
`fps`	float	Frames per second
`metadata`	object	Full ffprobe metadata (probe.json)
`created_at`	string	Registration timestamp (ISO 8601)

Error Codes

HTTP	When
`404`	File UUID not found

`GET /api/v1/file/:file_uuid/identities`

Auth: Required Scope: file-level

Get all identities present in a specific file with pagination.

Query Parameters

Field	Type	Required	Default	Description
`page`	integer	No	1	Page number
`page_size`	integer	No	20	Items per page

Example

curl -s "$API/api/v1/file/$FILE_UUID/identities?page=1&page_size=50" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "fps": 24.0,
  "total": 5,
  "page": 1,
  "page_size": 20,
  "data": [
    {
      "identity_id": 1,
      "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
      "name": "Audrey Hepburn",
      "metadata": {"source": "tmdb", "tmdb_id": 1234},
      "face_count": 142,
      "speaker_count": 8,
      "start_frame": 100,
      "end_frame": 5000,
      "start_time": 4.17,
      "end_time": 208.33,
      "confidence": 0.87
    }
  ]
}

Field	Type	Description
`data[].identity_id`	integer	Database identity ID
`data[].identity_uuid`	string/null	Global identity UUID (null if unbound)
`data[].name`	string	Identity name
`data[].metadata`	object	Source metadata (TMDb, etc.)
`data[].face_count`	integer/null	Number of face detections
`data[].speaker_count`	integer/null	Number of speaker segments
`data[].start_frame`	integer/null	First appearance frame
`data[].end_frame`	integer/null	Last appearance frame
`data[].start_time`	float/null	First appearance time (seconds)
`data[].end_time`	float/null	Last appearance time (seconds)
`data[].confidence`	float/null	Average detection confidence

`GET /api/v1/file/:file_uuid/faces`

Auth: Required Scope: file-level

List all face detections in a specific file with pagination.

Query Parameters

Field	Type	Required	Default	Description
`page`	integer	No	1	Page number
`page_size`	integer	No	50	Items per page

Example

curl -s "$API/api/v1/file/$FILE_UUID/faces?page=1&page_size=100" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
  "total": 1420,
  "page": 1,
  "page_size": 50,
  "data": [
    {
      "face_id": "face_100",
      "frame_number": 1200,
      "timestamp": 50.0,
      "bbox": [100, 50, 300, 400],
      "confidence": 0.95,
      "identity_id": 1,
      "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
      "trace_id": 2
    }
  ]
}

Field	Type	Description
`data[].face_id`	string	Face detection ID
`data[].frame_number`	integer	Frame number in video
`data[].timestamp`	float	Timestamp in seconds
`data[].bbox`	array	Bounding box `[x1, y1, x2, y2]`
`data[].confidence`	float	Detection confidence
`data[].identity_id`	integer/null	Bound identity ID (null if unbound)
`data[].identity_uuid`	string/null	Bound identity UUID (null if unbound)
`data[].trace_id`	integer/null	Face trace ID (null if not traced)

`POST /api/v1/file/:file_uuid/json/:processor`

Auth: Required Scope: file-level

Download raw JSON output for a specific processor.

Path Parameters

Field	Type	Required	Description
`file_uuid`	string	Yes	File UUID
`processor`	string	Yes	Processor name: `cut`, `asrx`, `yolo`, `ocr`, `face`, `pose`, `story`, etc.

Example

curl -s -X POST "$API/api/v1/file/$FILE_UUID/json/face" \
  -H "X-API-Key: $KEY" | jq '.frames | length'

Response (200)

Returns the raw JSON output of the specified processor. Structure varies by processor type.

Error Codes

HTTP	When
`404`	JSON file not found
`500`	Failed to parse JSON

Unregister

`POST /api/v1/unregister`

Auth: Required Scope: file-level

Delete a registered file from the system. Supports single file by UUID, or batch by directory + regex pattern.

What gets deleted

Removed (default)	Not removed
Database records (videos, chunks, embeddings, processor_results, pre_chunks)	The original source video file on disk
Processor output JSON files (`{uuid}.*.json`) — unless `delete_output_files: false`	Temp/working directories
In-memory cache entries
MongoDB cached lists

⚠️ Database deletion is irreversible. To keep output files, set "delete_output_files": false.

Request Parameters

At least one mode must be specified: either file_uuid alone, or file_path + pattern together.

Field	Type	Required	Default	Description
`file_uuid`	string	*	—	Single file UUID to delete
`file_path`	string	*	—	Directory path (for batch delete)
`pattern`	string	*	—	Regex pattern (requires `file_path`)
`delete_output_files`	boolean	No	`true`	If `true`, also delete processor output JSON files (`{uuid}.*.json`). Set to `false` to keep them.

Example

# Delete a single file by UUID (default: also deletes output JSON files)
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'"}'

# Keep output JSON files, only delete DB records
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "delete_output_files": false}'

# Batch delete all mp4 files in a directory
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'

Response (200)

{
  "success": true,
  "file_uuid": "a03485a40b2df2d3",
  "message": "Video unregistered successfully"
}

Field	Type	Description
`success`	boolean	True if deletion succeeded
`file_uuid`	string	UUID of the deleted file (single mode)
`message`	string	Human-readable status

Error Responses

HTTP	When
`400`	Neither `file_uuid` nor `file_path`+`pattern` provided
`404`	File UUID not found
`401`	Missing or invalid API key

Updated: 2026-06-20 — Added file listing, file detail, file identities, file faces, and JSON download endpoints