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.

POST /deepSearch

Create a deep search

cURL

curl --request POST \
  --url https://api.cloudglue.dev/v1/deepSearch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledge_base": {
    "source": "collections",
    "collections": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "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>"
          ]
        }
      ]
    }
  },
  "query": "<string>",
  "scope": "segment",
  "limit": 20,
  "exclude_weak_results": false,
  "include": [
    "search_queries"
  ],
  "stream": false,
  "background": false
}
'

import requests

url = "https://api.cloudglue.dev/v1/deepSearch"

payload = {
    "knowledge_base": {
        "source": "collections",
        "collections": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
        "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>"]
                }
            ]
        }
    },
    "query": "<string>",
    "scope": "segment",
    "limit": 20,
    "exclude_weak_results": False,
    "include": ["search_queries"],
    "stream": False,
    "background": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    knowledge_base: {
      source: 'collections',
      collections: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
      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>']}]
      }
    },
    query: '<string>',
    scope: 'segment',
    limit: 20,
    exclude_weak_results: false,
    include: ['search_queries'],
    stream: false,
    background: false
  })
};

fetch('https://api.cloudglue.dev/v1/deepSearch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloudglue.dev/v1/deepSearch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'knowledge_base' => [
        'source' => 'collections',
        'collections' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ],
        '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>'
                                                                ]
                                ]
                ]
        ]
    ],
    'query' => '<string>',
    'scope' => 'segment',
    'limit' => 20,
    'exclude_weak_results' => false,
    'include' => [
        'search_queries'
    ],
    'stream' => false,
    'background' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloudglue.dev/v1/deepSearch"

	payload := strings.NewReader("{\n  \"knowledge_base\": {\n    \"source\": \"collections\",\n    \"collections\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"filter\": {\n      \"metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"video_info\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"file\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"source_metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ]\n    }\n  },\n  \"query\": \"<string>\",\n  \"scope\": \"segment\",\n  \"limit\": 20,\n  \"exclude_weak_results\": false,\n  \"include\": [\n    \"search_queries\"\n  ],\n  \"stream\": false,\n  \"background\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloudglue.dev/v1/deepSearch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"knowledge_base\": {\n    \"source\": \"collections\",\n    \"collections\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"filter\": {\n      \"metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"video_info\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"file\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"source_metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ]\n    }\n  },\n  \"query\": \"<string>\",\n  \"scope\": \"segment\",\n  \"limit\": 20,\n  \"exclude_weak_results\": false,\n  \"include\": [\n    \"search_queries\"\n  ],\n  \"stream\": false,\n  \"background\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloudglue.dev/v1/deepSearch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"knowledge_base\": {\n    \"source\": \"collections\",\n    \"collections\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"filter\": {\n      \"metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"video_info\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"file\": [\n        {\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"source_metadata\": [\n        {\n          \"path\": \"<string>\",\n          \"valueText\": \"<string>\",\n          \"valueTextArray\": [\n            \"<string>\"\n          ]\n        }\n      ]\n    }\n  },\n  \"query\": \"<string>\",\n  \"scope\": \"segment\",\n  \"limit\": 20,\n  \"exclude_weak_results\": false,\n  \"include\": [\n    \"search_queries\"\n  ],\n  \"stream\": false,\n  \"background\": false\n}"

response = http.request(request)
puts response.read_body

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "deep_search",
  "created_at": 123,
  "query": "<string>",
  "text": "<string>",
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "collection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "score": 123,
      "context": "<string>",
      "segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "start_time": 123,
      "end_time": 123,
      "title": "<string>",
      "filename": "<string>",
      "thumbnail_url": "<string>",
      "metadata": {},
      "summary": "<string>",
      "generated_title": "<string>"
    }
  ],
  "total": 123,
  "limit": 123,
  "search_queries": [
    {
      "query": "<string>",
      "search_modalities": [
        "<string>"
      ],
      "scope": "<string>",
      "filter": {},
      "result_count": 123
    }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "search_calls": 123
  },
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>"
  }
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Authorizations

Authorization · string · header · required

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

Body

application/json

Deep search creation parameters

knowledge_base · object · required

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

Option 1

Option 2

Option 3

Show child attributes

query · string · required

The search query.

Minimum string length: 1

scope · enum<string> · default: segment

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

Available options: segment, file

limit · integer · default: 20

Maximum number of results to return. Actual count may be lower when exclude_weak_results is enabled.

Required range: 1 <= x <= 500

exclude_weak_results · boolean · default: false

When true, removes results tagged as weak matches by the synthesis LLM.

include · enum<string>[]

Additional fields to include in the response. 'search_queries' includes the intermediate search query plan.

Available options: search_queries

stream · boolean · default: false

Stream the response via SSE. Mutually exclusive with background.

background · boolean · default: false

Process in the background. Returns immediately with status 'in_progress'. Mutually exclusive with stream.

Response

200

application/json

Deep search created successfully

id · string<uuid>

Deep search ID

object · enum<string>

Object type identifier

Available options: deep_search

status · enum<string>

Current status of the deep search

Available options: in_progress, completed, failed, cancelled

created_at · number

Unix timestamp of when the deep search was created

query · string

The original search query

scope · enum<string>

The scope of the search results

Available options: segment, file

text · string | null

LLM-generated synthesis text summarizing the results

results · object[] | null

Array of search results

Show child attributes

total · integer

Total number of results

limit · integer

Maximum number of results requested

search_queries · object[] | null

Intermediate search query plans (included when requested via include=['search_queries'])

Show child attributes

usage · object | null

Token and search call usage

Show child attributes

error · object | null

Error details if the deep search failed

Show child attributes