> ## 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.

# Create Deep Search

> Create a new deep search over one or more collections. Deep search uses agentic retrieval and LLM summarization to find specific moments across your video data.

The search can be processed synchronously (default), streamed via SSE, or run in the background.



## OpenAPI

````yaml POST /deepSearch
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.13
servers:
  - url: https://api.cloudglue.dev/v1
security:
  - bearerAuth: []
paths:
  /deepSearch:
    post:
      tags:
        - Deep Search
      summary: Create a deep search
      description: >-
        Create a new deep search over one or more collections. Deep search uses
        agentic retrieval and LLM summarization to find specific moments across
        your video data.


        The search can be processed synchronously (default), streamed via SSE,
        or run in the background.
      operationId: createDeepSearch
      requestBody:
        description: Deep search creation parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeepSearchRequest'
        required: true
      responses:
        '200':
          description: Deep search created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepSearch'
        '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:
    CreateDeepSearchRequest:
      type: object
      required:
        - query
        - knowledge_base
      properties:
        knowledge_base:
          description: >-
            Knowledge base configuration. Determines which content to search.


            Three source modes are supported:

            - `collections`: Search within specific collections

            - `files`: Search specific files by URL or file ID (uses default
            index)

            - `default`: Search all default-indexed files for the account
          oneOf:
            - $ref: '#/components/schemas/DeepSearchKBCollections'
            - $ref: '#/components/schemas/DeepSearchKBFiles'
            - $ref: '#/components/schemas/DeepSearchKBDefault'
        query:
          type: string
          minLength: 1
          description: The search query.
        scope:
          type: string
          enum:
            - segment
            - file
          default: segment
          description: >-
            The scope of results to return. 'segment' returns individual
            segments, 'file' returns file-level results. When the knowledge base
            contains any metadata collections, scope must be 'file' (metadata
            collections only index file-level documents).
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 20
          description: >-
            Maximum number of results to return. Actual count may be lower when
            exclude_weak_results is enabled.
        exclude_weak_results:
          type: boolean
          default: false
          description: >-
            When true, removes results tagged as weak matches by the synthesis
            LLM.
        include:
          type: array
          items:
            type: string
            enum:
              - search_queries
          description: >-
            Additional fields to include in the response. 'search_queries'
            includes the intermediate search query plan.
        stream:
          type: boolean
          default: false
          description: Stream the response via SSE. Mutually exclusive with background.
        background:
          type: boolean
          default: false
          description: >-
            Process in the background. Returns immediately with status
            'in_progress'. Mutually exclusive with stream.
    DeepSearch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Deep search ID
        object:
          type: string
          enum:
            - deep_search
          description: Object type identifier
        status:
          type: string
          enum:
            - in_progress
            - completed
            - failed
            - cancelled
          description: Current status of the deep search
        created_at:
          type: number
          description: Unix timestamp of when the deep search was created
        query:
          type: string
          description: The original search query
        scope:
          type: string
          enum:
            - segment
            - file
          description: The scope of the search results
        text:
          type: string
          nullable: true
          description: LLM-generated synthesis text summarizing the results
        results:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/DeepSearchResult'
          description: Array of search results
        total:
          type: integer
          description: Total number of results
        limit:
          type: integer
          description: Maximum number of results requested
        search_queries:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/DeepSearchSearchQueryPlan'
          description: >-
            Intermediate search query plans (included when requested via
            include=['search_queries'])
        usage:
          $ref: '#/components/schemas/DeepSearchUsage'
          nullable: true
          description: Token and search call usage
        error:
          type: object
          nullable: true
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
          description: Error details if the deep search failed
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
    DeepSearchKBCollections:
      type: object
      description: Search within specific collections.
      required:
        - source
        - collections
      properties:
        source:
          type: string
          enum:
            - collections
          description: Source mode identifier.
        collections:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: >-
            Collection IDs to search. Collections must be of type
            rich-transcripts or media-descriptions.
        filter:
          description: Optional filter to narrow down the search within collections.
          allOf:
            - $ref: '#/components/schemas/SearchFilter'
    DeepSearchKBFiles:
      type: object
      description: >-
        Search specific files by URL or file ID. Files must have been described
        or added to a collection to be searchable.
      required:
        - source
        - files
      properties:
        source:
          type: string
          enum:
            - files
          description: Source mode identifier.
        files:
          type: array
          items:
            type: string
          minItems: 1
          description: >-
            File references to search. Can be file UUIDs, cloudglue URIs
            (`cloudglue://files/...`), data connector URLs, or HTTP URLs.
    DeepSearchKBDefault:
      type: object
      description: >-
        Search all default-indexed files for the account. Includes any file that
        has been described (with `use_in_default_index: true`) or added to a
        collection.
      required:
        - source
      properties:
        source:
          type: string
          enum:
            - default
          description: Source mode identifier.
    DeepSearchResult:
      type: object
      properties:
        type:
          type: string
          enum:
            - segment
            - file
          description: The type of result
        id:
          type: string
          format: uuid
          description: Result ID
        file_id:
          type: string
          format: uuid
          description: The file ID this result belongs to
        collection_id:
          type: string
          format: uuid
          description: >-
            The collection ID this result belongs to. Present when using
            `collections` source; omitted for `files` and `default` sources.
        score:
          type: number
          description: Relevance score
        context:
          type: string
          description: LLM-generated context explaining why this result is relevant
        segment_id:
          type: string
          format: uuid
          description: Segment ID (present when type is 'segment')
        start_time:
          type: number
          description: Start time in seconds (present when type is 'segment')
        end_time:
          type: number
          description: End time in seconds (present when type is 'segment')
        title:
          type: string
          nullable: true
          description: Segment title
        filename:
          type: string
          nullable: true
          description: Original filename
        thumbnail_url:
          type: string
          nullable: true
          description: URL to a thumbnail image
        metadata:
          type: object
          nullable: true
          description: Additional metadata
        summary:
          type: string
          nullable: true
          description: File summary (present when type is 'file')
        generated_title:
          type: string
          nullable: true
          description: Generated title (present when type is 'file')
    DeepSearchSearchQueryPlan:
      type: object
      properties:
        query:
          type: string
          description: The search query
        search_modalities:
          type: array
          items:
            type: string
          description: Modalities used for this search
        scope:
          type: string
          description: Search scope
        filter:
          type: object
          nullable: true
          description: Optional filter applied
        result_count:
          type: integer
          description: Number of results returned for this query
    DeepSearchUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens used
        output_tokens:
          type: integer
          description: Number of output tokens used
        total_tokens:
          type: integer
          description: Total number of tokens used
        search_calls:
          type: integer
          description: Number of search calls made
    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
        source_metadata:
          type: array
          description: >-
            Filter by connector-provided source metadata using JSON path
            expressions (file scope only). Available fields depend on the file's
            source. Examples: source_metadata.topic (zoom),
            source_metadata.host_email (zoom), source_metadata.title
            (gong/grain/iconik), source_metadata.participants.name (grain),
            source_metadata.parties.email (gong), source_metadata.tags (grain,
            use ContainsAny), source_metadata.meeting_platform (recall),
            source_metadata.name (google-drive/dropbox),
            source_metadata.media_type (iconik),
            source_metadata.iconik_metadata.<FieldName> (iconik custom
            metadata-view fields, e.g. source_metadata.iconik_metadata.Keywords
            with ContainsAny). Paths through arrays of objects match when ANY
            element matches. ISO datetime fields (zoom start_time, gong started,
            grain start_datetime, recall started_at, iconik date_created)
            compare as strings with LessThan/GreaterThan and represent the
            actual meeting date (or, for iconik, the asset creation date).
          items:
            $ref: '#/components/schemas/SearchFilterCriteria'
    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)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````