Search Content

Search for videos or video segments in collections to find relevant videos or moments/clips in a video

POST /search

Search across video files and segments to find relevant content

cURL

curl --request POST \
  --url https://api.cloudglue.dev/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "collections": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "query": "<string>",
  "criterion_name": "<string>",
  "source_image": {
    "url": "<string>",
    "base64": "<string>"
  },
  "limit": 2,
  "filter": {
    "metadata": [
      {
        "path": "<string>",
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ],
    "video_info": [
      {
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ],
    "file": [
      {
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ],
    "source_metadata": [
      {
        "path": "<string>",
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ]
  },
  "threshold": 123,
  "group_by_key": "file",
  "search_modalities": [],
  "label_filters": [
    "<string>"
  ]
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "search",
  "scope": "file",
  "results": [
    {
      "type": "file",
      "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "collection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "score": 123,
      "filename": "<string>",
      "summary": "<string>",
      "generated_title": "<string>",
      "thumbnail_url": "<string>",
      "tag": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "value": "<string>",
        "label": "<string>"
      }
    }
  ],
  "total": 123,
  "limit": 123,
  "query": "<string>",
  "group_by_key": "file",
  "group_count": 123,
  "search_modalities": [
    "general_content"
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Search parameters

scope · enum<string>

Search scope - 'file' searches at file level (requires collections with enable_summary=true), 'segment' searches at segment level, 'face' searches for faces in videos using image matching, 'moment' searches moments produced by find-moments criteria in moments collections

Available options: file, segment, face, moment

collections · string<uuid>[]

List of collection IDs to search within.

For text search (scope='file' or 'segment'): All collections must be of collection_type 'media-descriptions', 'rich-transcripts', 'metadata', or 'entities'. For file-level search, 'media-descriptions' and 'rich-transcripts' collections must have 'enable_summary: true' in their config. 'metadata' collections only support scope='file'. 'entities' collections are searchable at the scope matching their extraction level: file-level extraction (enable_video_level_entities or enable_metadata_mode) supports scope='file' only, segment-level extraction (enable_segment_level_entities) supports scope='segment' only.

For face search (scope='face'): All collections must be of collection_type 'face-analysis'.

For moment search (scope='moment'): All collections must be of collection_type 'moments'.

Minimum array length: 1

query · string

Text search query to find relevant content (required for scope='file', 'segment', or 'moment')

Minimum string length: 1

criterion_name · string

Narrow moment search to one criterion by name (scope='moment' only)

source_image · object

Source image for face search (required for scope='face')

Show child attributes

limit · integer

Maximum number of search results to return (applies to total items across groups when grouping)

Required range: x >= 1

filter · object

Show child attributes

threshold · number

Minimum score threshold to filter results. Can be any real number.

group_by_key · enum<string>

Group results by file. Cannot be used with scope="file" or scope="moment" — grouped moment search is not supported and returns a 400. When specified, results are grouped by file_id.

Available options: file

sort_by · enum<string>

Sort order for results. Default: "score". When group_by_key is specified, can also use "item_count" to sort by number of items per group.

Available options: score, item_count

search_modalities · enum<string>[]

Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality.

Available modalities:

• general_content: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string
• speech_lexical: performs keyword based search (e.g. query of president matching president or presidential strings) and exact match (e.g. specifically find mentions of "Barack Obama" or "Donald Trump") against speech content present in search item
• ocr_lexical: performs keyword based search and exact match against screen text content present in search item
• tag_semantic: performs basic word semantic similarity search against tag values associated with search items (e.g. query=animal expected to match tags with value containing dog or cat)
• tag_lexical: performs keyword based search and exact match against tag values associated with search items
• doc_lexical: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search scope=file.

Only applicable when search scope=file or scope=segment.

Maximum array length: 5

Available options: general_content, speech_lexical, ocr_lexical, tag_semantic, tag_lexical, doc_lexical

label_filters · string[]

Filter eligible search items by presence of one or more labels in the provided list (otherwise all tags will be considered in search response). Only supported for tag_semantic and tag_lexical search modalities

Response

200

application/json

Successful search results

id · string<uuid> · required

ID of the search response

object · enum<string> · required

Object type, always 'search'

Available options: search

scope · enum<string> · required

The search scope that was used

Available options: file, segment, face, moment

results · object[] · required

Array of search results ranked by relevance score

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

total · integer · required

Total number of results returned. When group_by_key is specified, this represents the total number of items across all groups (not the number of groups).

limit · integer · required

The limit that was applied to the search

query · string

The search query that was executed (for text search) or the source image URL/base64 indicator (for face search)

group_by_key · enum<string>

The key used for grouping results. Only present when group_by_key was specified in the request and results are grouped.

Available options: file

group_count · integer

Number of groups in the results. Only present when group_by_key is specified.

search_modalities · enum<string>[]

Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality.

Available modalities:

• general_content: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string
• speech_lexical: performs keyword based search (e.g. query of president matching president or presidential strings) and exact match (e.g. specifically find mentions of "Barack Obama" or "Donald Trump") against speech content present in search item
• ocr_lexical: performs keyword based search and exact match against screen text content present in search item
• tag_semantic: performs basic word semantic similarity search against tag values associated with search items (e.g. query=animal expected to match tags with value containing dog or cat)
• tag_lexical: performs keyword based search and exact match against tag values associated with search items
• doc_lexical: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search scope=file.

Only applicable when search scope=file or scope=segment.

Maximum array length: 5

Available options: general_content, speech_lexical, ocr_lexical, tag_semantic, tag_lexical, doc_lexical