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>"
        ]
      }
    ],
    "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"
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "search",
  "query": "<string>",
  "scope": "file",
  "group_by_key": "file",
  "group_count": 123,
  "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>"
    }
  ],
  "total": 123,
  "limit": 123
}

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 length: 1
​
query
string

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

Minimum 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

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

  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
​
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.