Skip to main content
POST
/
search
Search across video files and segments to find relevant content
curl --request POST \
  --url https://api.cloudglue.dev/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "file",
  "collections": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "query": "<string>",
  "source_image": {
    "url": "<string>",
    "base64": "<string>"
  },
  "limit": 10,
  "filter": {
    "metadata": [
      {
        "path": "<string>",
        "operator": "NotEqual",
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ],
        "scope": "file"
      }
    ],
    "video_info": [
      {
        "path": "duration_seconds",
        "operator": "NotEqual",
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ],
    "file": [
      {
        "path": "bytes",
        "operator": "NotEqual",
        "valueText": "<string>",
        "valueTextArray": [
          "<string>"
        ]
      }
    ]
  },
  "threshold": 123,
  "group_by_key": "file",
  "sort_by": "score",
  "search_modalities": [
    "general_content"
  ],
  "label_filters": [
    "<string>"
  ]
}
'
{
  "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

Available options:
file,
segment,
face
​
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' or 'rich-transcripts'. For file-level search, collections must have 'enable_summary: true' in transcribe_config.

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

Minimum array length: 1
​
query
string

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

Minimum string length: 1
​
source_image
object

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

​
limit
integer
default:10

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

Required range: x >= 1
​
filter
object
​
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". When specified, results are grouped by file_id.

Available options:
file
​
sort_by
enum<string>
default:score

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 of search to execute, one of:

  • 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

This API currently only supports one search modality per request.

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

Available options:
general_content,
speech_lexical,
ocr_lexical,
tag_semantic,
tag_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

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
​
results
object[]
required

Array of search results ranked by relevance score

​
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 of search to execute, one of:

  • 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

This API currently only supports one search modality per request.

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

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