> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Content

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



## OpenAPI

````yaml POST /search
openapi: 3.0.0
info:
  title: Cloudglue API
  description: API for Cloudglue
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 0.7.8
servers:
  - url: https://api.cloudglue.dev/v1
security:
  - bearerAuth: []
paths:
  /search:
    post:
      tags:
        - Search
      summary: Search across video files and segments to find relevant content
      description: >-
        Search for videos or video segments in collections to find relevant
        videos or moments/clips in a video
      operationId: searchContent
      requestBody:
        description: Search parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchRequest:
      type: object
      properties:
        scope:
          type: string
          enum:
            - file
            - segment
            - face
          description: >-
            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
        collections:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: >-
            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'.
        query:
          type: string
          minLength: 1
          description: >-
            Text search query to find relevant content (required for
            scope='file' or 'segment')
        source_image:
          type: object
          description: Source image for face search (required for scope='face')
          properties:
            url:
              type: string
              description: URL of the source image to search for
            base64:
              type: string
              description: Base64-encoded image bytes
        limit:
          type: integer
          minimum: 1
          description: >-
            Maximum number of search results to return (applies to total items
            across groups when grouping)
        filter:
          $ref: '#/components/schemas/SearchFilter'
        threshold:
          type: number
          description: Minimum score threshold to filter results. Can be any real number.
        group_by_key:
          type: string
          enum:
            - file
          description: >-
            Group results by file. Cannot be used with scope="file". When
            specified, results are grouped by file_id.
        sort_by:
          type: string
          enum:
            - score
            - item_count
          description: >-
            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.
        search_modalities:
          $ref: '#/components/schemas/SearchModalities'
        label_filters:
          type: array
          items:
            type: string
          description: >-
            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 
    SearchResponse:
      type: object
      required:
        - id
        - object
        - scope
        - results
        - total
        - limit
      properties:
        id:
          type: string
          format: uuid
          description: ID of the search response
        object:
          type: string
          enum:
            - search
          description: Object type, always 'search'
        query:
          type: string
          description: >-
            The search query that was executed (for text search) or the source
            image URL/base64 indicator (for face search)
        scope:
          type: string
          enum:
            - file
            - segment
            - face
          description: The search scope that was used
        group_by_key:
          type: string
          enum:
            - file
          description: >-
            The key used for grouping results. Only present when group_by_key
            was specified in the request and results are grouped.
        group_count:
          type: integer
          description: >-
            Number of groups in the results. Only present when group_by_key is
            specified.
        search_modalities:
          $ref: '#/components/schemas/SearchModalities'
        results:
          type: array
          description: Array of search results ranked by relevance score
          items:
            oneOf:
              - $ref: '#/components/schemas/FileSearchResult'
              - $ref: '#/components/schemas/SegmentSearchResult'
              - $ref: '#/components/schemas/FaceSearchResult'
              - $ref: '#/components/schemas/SegmentGroupResult'
              - $ref: '#/components/schemas/FaceGroupResult'
        total:
          type: integer
          description: >-
            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:
          type: integer
          description: The limit that was applied to the search
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
    SearchFilter:
      type: object
      properties:
        metadata:
          type: array
          description: Filter by file metadata using JSON path expressions
          items:
            allOf:
              - $ref: '#/components/schemas/SearchFilterCriteria'
              - type: object
                properties:
                  scope:
                    type: string
                    enum:
                      - file
                      - segment
                    description: >-
                      Specifies scope of eligible search items (file/segment) to
                      check metadata filtering conditions
        video_info:
          type: array
          description: >-
            Filter by video information. Use scope 'file' to filter by source
            video properties, or 'segment' to filter by individual segment
            properties (e.g. segment duration).
          items:
            allOf:
              - $ref: '#/components/schemas/SearchFilterCriteria'
              - type: object
                properties:
                  path:
                    type: string
                    enum:
                      - duration_seconds
                      - has_audio
                  scope:
                    type: string
                    enum:
                      - file
                      - segment
                    description: >-
                      Scope of the filter. 'file' filters by source video
                      properties, 'segment' filters by segment properties. Only
                      duration_seconds is supported with segment scope.
        file:
          type: array
          description: Filter by file properties
          items:
            allOf:
              - $ref: '#/components/schemas/SearchFilterCriteria'
              - type: object
                properties:
                  path:
                    type: string
                    enum:
                      - bytes
                      - filename
                      - uri
                      - created_at
                      - id
    SearchModalities:
      type: array
      items:
        type: string
        enum:
          - general_content
          - speech_lexical
          - ocr_lexical
          - tag_semantic
          - tag_lexical
      maxItems: 5
      description: >
        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


        Only applicable when search `scope=file` or `scope=segment`.
    FileSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - score
        - id
      properties:
        type:
          type: string
          enum:
            - file
          description: Result type, always 'file'
        file_id:
          type: string
          format: uuid
          description: ID of the file
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        id:
          type: string
          format: uuid
          description: ID of the search document
        score:
          type: number
          description: Relevance score (higher is more relevant)
        filename:
          type: string
          nullable: true
          description: Original filename of the video
        summary:
          type: string
          nullable: true
          description: Generated summary of the video
        generated_title:
          type: string
          nullable: true
          description: Generated title of the video
        thumbnail_url:
          type: string
          format: uri
          description: URL of the thumbnail for the file if available.
        tag:
          $ref: '#/components/schemas/SearchTagResponse'
    SegmentSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - segment_id
        - score
        - id
        - start_time
        - end_time
      properties:
        type:
          type: string
          enum:
            - segment
          description: Result type, always 'segment'
        file_id:
          type: string
          format: uuid
          description: ID of the file
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        segment_id:
          type: string
          format: uuid
          description: ID of the segment
        id:
          type: string
          format: uuid
          description: ID of the search document
        score:
          type: number
          description: Relevance score (higher is more relevant)
        start_time:
          type: number
          description: Start time of the segment in seconds
        end_time:
          type: number
          description: End time of the segment in seconds
        title:
          type: string
          nullable: true
          description: Title associated with the segment
        filename:
          type: string
          nullable: true
          description: Original filename of the video
        visual_description:
          type: array
          description: Visual descriptions for the segment
          items:
            type: object
            properties:
              text:
                type: string
                description: Description of visual content in the segment
              start_time:
                type: number
                description: Start time of the visual content in seconds
              end_time:
                type: number
                description: End time of the visual content in seconds
        scene_text:
          type: array
          description: Text detected on screen in the segment
          items:
            type: object
            properties:
              text:
                type: string
                description: Text detected on screen
              start_time:
                type: number
                description: Start time of the text in seconds
              end_time:
                type: number
                description: End time of the text in seconds
        speech:
          type: array
          description: Speech transcription for the segment
          items:
            type: object
            properties:
              speaker:
                type: string
                description: Identified speaker
              text:
                type: string
                description: Transcribed speech text
              start_time:
                type: number
                description: Start time of speech in seconds
              end_time:
                type: number
                description: End time of speech in seconds
        thumbnail_url:
          type: string
          format: uri
          description: URL of the thumbnail for the segment if available
        tag:
          $ref: '#/components/schemas/SearchTagResponse'
        metadata:
          type: object
          description: User-provided metadata about the segment, if provided.
        keyframes:
          type: array
          description: Keyframes for the segment
          items:
            type: object
            properties:
              time_in_seconds:
                type: number
                description: Time of the keyframe in seconds
              thumbnail_url:
                type: string
                format: uri
                description: URL of the thumbnail for the keyframe
    FaceSearchResult:
      type: object
      required:
        - type
        - file_id
        - collection_id
        - face_id
        - frame_id
        - score
        - timestamp
      properties:
        type:
          type: string
          enum:
            - face
          description: Result type, always 'face'
        file_id:
          type: string
          format: uuid
          description: ID of the file containing the matched face
        collection_id:
          type: string
          format: uuid
          description: ID of the collection containing this file
        face_id:
          type: string
          format: uuid
          description: ID of the detected face
        frame_id:
          type: string
          format: uuid
          description: ID of the frame where the face was detected
        score:
          type: number
          description: Similarity score (higher is more similar)
        timestamp:
          type: number
          minimum: 0
          description: Timestamp of the frame in seconds
        face_bounding_box:
          type: object
          required:
            - height
            - width
            - top
            - left
          properties:
            height:
              type: number
              minimum: 0
              maximum: 1
              description: Height of the bounding box (normalized 0-1)
            width:
              type: number
              minimum: 0
              maximum: 1
              description: Width of the bounding box (normalized 0-1)
            top:
              type: number
              minimum: 0
              maximum: 1
              description: Top position of the bounding box (normalized 0-1)
            left:
              type: number
              minimum: 0
              maximum: 1
              description: Left position of the bounding box (normalized 0-1)
        thumbnail_url:
          type: string
          description: URL of the frame thumbnail
    SegmentGroupResult:
      type: object
      required:
        - type
        - matched_items
        - file_id
        - item_count
        - best_score
      properties:
        type:
          type: string
          enum:
            - segment_group
          description: Result type, always 'segment_group'
        matched_items:
          type: array
          items:
            $ref: '#/components/schemas/SegmentSearchResult'
          description: Array of segment search results that belong to this file
        file_id:
          type: string
          format: uuid
          description: ID of the file that this group represents
        item_count:
          type: integer
          description: Number of matched items in this group
        best_score:
          type: number
          description: The highest score among all items in this group
    FaceGroupResult:
      type: object
      required:
        - type
        - matched_items
        - file_id
        - item_count
        - best_score
      properties:
        type:
          type: string
          enum:
            - face_group
          description: Result type, always 'face_group'
        matched_items:
          type: array
          items:
            $ref: '#/components/schemas/FaceSearchResult'
          description: Array of face search results that belong to this file
        file_id:
          type: string
          format: uuid
          description: ID of the file that this group represents
        item_count:
          type: integer
          description: Number of matched items in this group
        best_score:
          type: number
          description: The highest score among all items in this group
    SearchFilterCriteria:
      type: object
      required:
        - path
        - operator
      properties:
        path:
          type: string
          description: JSON path for the field to filter on
        operator:
          type: string
          enum:
            - NotEqual
            - Equal
            - LessThan
            - GreaterThan
            - ContainsAny
            - ContainsAll
            - In
            - Like
          description: Comparison operator to apply
        valueText:
          type: string
          description: >-
            Text value for scalar comparison (used with NotEqual, Equal,
            LessThan, GreaterThan, Like)
        valueTextArray:
          type: array
          items:
            type: string
          description: >-
            Array of values for array comparisons (used with ContainsAny,
            ContainsAll, In)
    SearchTagResponse:
      type: object
      description: >-
        The associated tag for the search result if it exists. Only provided for
        search requests with tag_semantic or tag_lexical search modalities.
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the tag
        value:
          type: string
          description: The value of the tag
        label:
          type: string
          description: The label of the tag
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````