06 Search - Momentry API Docs

Search APIs

`POST /api/v1/search/smart`

Auth: Required Scope: 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
`file_uuid`	string	Yes	—	File UUID to search within
`query`	string	Yes	—	Search text
`limit`	integer	No	5	Max results to return
`page`	integer	No	1	Page number
`page_size`	integer	No	5	Items per page

Example

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": [
    {
      "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"
}

`POST /api/v1/search/universal`

Auth: Required Scope: 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
`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

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",
      "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
    }
  ],
  "total": 20,
  "took_ms": 18
}

`POST /api/v1/search/frames`

Auth: Required Scope: file-level

Search face detection frames by identity name or trace ID.

`POST /api/v1/search/identity_text`

Auth: Required Scope: file-level

Search text chunks spoken by a specific identity.

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)