Cerul
Log in
API reference

Copy manually

Clipboard access was denied. Copy the selected text below.

API reference / Search

POST/search

Search your videos

Base URL https://api.cerul.aiVersion 1.0.0-foundationBearer

Required scopes

videos:read

Returns the clips that best answer the query, across all videos in the workspace unless `filter.video_ids` narrows it. Requires a verified email and sufficient prepaid credits. Results are ordered by fused relevance; `score` is the raw similarity within the clip's own `type` and is not comparable across types or a correctness probability. When nothing is close enough the response has an empty `data` and the `no_confident_match` warning; that completed search is still billed. A search with no indexed videos is not billed. `playback.url` and `thumbnail_url` expire after one hour; store `console_url` instead. Reuse the same Idempotency-Key only with unchanged input.

Parameters

Idempotency-Keyheader · Required

application/json · search

querystring · Required

filterobject

Omit to search every video in the workspace.

limitinteger

includearray

Optional extra blocks. `debug` adds model, version and ranking details to each clip.

Request · Schema
{
  "schema": {
    "$ref": "#/components/schemas/SearchRequest"
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "filter": {
            "description": "Omit to search every video in the workspace.",
            "$ref": "#/components/schemas/SearchFilter"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          },
          "include": {
            "description": "Optional extra blocks. `debug` adds model, version and ranking details to each clip.",
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "debug"
              ]
            }
          }
        }
      },
      "SearchFilter": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "video_ids": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/VideoId"
            }
          }
        },
        "description": "Omit to search every video in the workspace."
      },
      "VideoId": {
        "description": "A Video is the developer-facing name for a media Asset, and shares its identifier.",
        "type": "string",
        "pattern": "^asset_[A-Za-z0-9_-]+$"
      }
    }
  }
}