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

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