06 Search - Momentry API Docs

Search APIs

`POST /api/v1/search/smart`

Auth: Required Scope: global / file-level

Semantic vector search using EmbeddingGemma-300m. Generates a query embedding via EmbeddingGemma (port 11436), then searches pgvector story_parent and llm_parent chunks by cosine similarity.

Request Parameters

Field	Type	Required	Default	Description
`query`	string	Yes	—	Search text
`file_uuid`	string	No	—	File UUID to search within. If omitted, searches all files (global search)
`limit`	integer	No	5	Max results to return
`page`	integer	No	1	Page number
`page_size`	integer	No	5	Items per page

Example (Global Search)

curl -s -X POST "$API/api/v1/search/smart" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"query": "Audrey Hepburn"}'

Example (File-specific Search)

curl -s -X POST "$API/api/v1/search/smart" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "query": "Audrey Hepburn"}'

Response (200)

{
  "query": "Audrey Hepburn",
  "results": [
    {
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "parent_id": 1087822,
      "scene_order": 1087822,
      "start_frame": 104438,
      "end_frame": 104538,
      "fps": 24.0,
      "start_time": 4351.6,
      "end_time": 4355.76,
      "summary": "[4352s-4356s, 4s] Cast: Audrey Hepburn. Total: 2 lines, 10 words. Speakers: Audrey Hepburn (2 lines)",
      "similarity": 0.67
    }
  ],
  "page": 1,
  "page_size": 5,
  "strategy": "semantic_vector_search"
}

Field	Type	Description
`results[].file_uuid`	string	File UUID where result was found

`POST /api/v1/search/universal`

Auth: Required Scope: global / file-level

Multi-type BM25 full-text search across chunks, frames, and persons. Uses PostgreSQL tsvector.

Request Parameters

Field	Type	Required	Default	Description
`query`	string	Yes	—	Search text
`file_uuid`	string	No	—	Restrict to specific file. If omitted, searches all files (global search)
`types`	string[]	No	`["chunk","frame","person"]`	Search types
`limit`	integer	No	10	Max results per type
`page`	integer	No	1	Page number
`page_size`	integer	No	20	Items per page

Example (Global Search)

curl -s -X POST "$API/api/v1/search/universal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"query": "Cary Grant"}'

Example (File-specific Search)

curl -s -X POST "$API/api/v1/search/universal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "query": "Cary Grant"}'

Response (200)

{
  "results": [
    {
      "type": "chunk",
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "chunk_id": "bd80fec92b0b6963d177a2c55bf713e2_2",
      "chunk_type": "story_child",
      "start_frame": 5103,
      "end_frame": 5127,
      "start_time": 212.64,
      "end_time": 213.64,
      "text": "[213s-214s] Cary Grant: \"Olá!\"",
      "score": 0.9
    },
    {
      "type": "frame",
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "frame_number": 5105,
      "timestamp": 212.72,
      "score": 0.7,
      "objects": null,
      "ocr_texts": null,
      "faces": null
    },
    {
      "type": "person",
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "identity_id": 12,
      "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
      "name": "Cary Grant",
      "appearance_count": 542,
      "score": 0.95
    }
  ],
  "total": 20,
  "took_ms": 18
}

Field	Type	Description
`results[].type`	string	Result type: `chunk`, `frame`, or `person`
`results[].file_uuid`	string	File UUID where result was found (all types)

`POST /api/v1/search/frames`

Auth: Required Scope: global / file-level

Search face detection frames by identity name or trace ID.

`GET /api/v1/search/identity_text`

Auth: Required Scope: global / file-level

Search text chunks → find associated identities. Returns chunks where face detections overlap with text content.

Query Parameters

Field	Type	Required	Default	Description
`q`	string	Yes	—	Search text (ILIKE match)
`file_uuid`	string	No	—	Restrict to specific file. If omitted, searches all files (global search)
`limit`	integer	No	50	Max results
`page`	integer	No	1	Page number
`page_size`	integer	No	50	Items per page

Example (Global Search)

curl -s "$API/api/v1/search/identity_text?q=love" -H "X-API-Key: $KEY"

Example (File-specific Search)

curl -s "$API/api/v1/search/identity_text?file_uuid=$FILE_UUID&q=love" -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "total": 5,
  "results": [
    {
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "chunk_id": "llm_parent_..._256_270",
      "start_time": 256.256,
      "end_time": 270.228,
      "text_content": "...lack of affection...",
      "identity_id": 9,
      "identity_name": "Audrey Hepburn",
      "identity_source": "tmdb",
      "trace_id": 94
    }
  ]
}

Field	Type	Description
`results[].file_uuid`	string	File UUID where chunk was found
`results[].identity_id`	integer	Identity ID if face was detected
`results[].trace_id`	integer	Face trace ID

Visual Search

Method	Endpoint	Description
POST	`/api/v1/search/visual`	Search visual chunks
POST	`/api/v1/search/visual/class`	Search by object class
POST	`/api/v1/search/visual/density`	Search by object density
POST	`/api/v1/search/visual/combination`	Search by object combination
POST	`/api/v1/search/visual/stats`	Visual chunk statistics

Embedding Model

Detail	Value
Model	EmbeddingGemma-300m
Endpoint	`POST /api/v1/embeddings` on port 11436
Dimension	768
Storage	pgvector (`chunk.embedding` column)

Updated: 2026-05-27 — Added global search support for smart, universal, identity_text APIs