Cerul
Log in
API reference

Copy manually

Clipboard access was denied. Copy the selected text below.

API reference / Search

POST/search

Search scoped libraries and assets for evidence

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

Required scopes

libraries:readassets:read

Cloud requests require verified email and sufficient prepaid credits. Omit filter to search the current workspace, or restrict by filter.video_ids or filter.library_ids. Scores rank candidate evidence; they are not correctness probabilities. A completed Cloud search with no matches may still be billable; a search with no indexed evidence is not billable. Reuse the same Idempotency-Key only with unchanged input.

Parameters

Idempotency-Keyheader · Required

application/json · searchEvidence

querystring · Required

filterobject

Omit to search the whole workspace.

execution_policystring

limitinteger

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 the whole workspace.",
            "$ref": "#/components/schemas/SearchFilter"
          },
          "execution_policy": {
            "$ref": "#/components/schemas/ExecutionPolicy"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          }
        }
      },
      "SearchFilter": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "video_ids": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/VideoId"
            }
          },
          "library_ids": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/LibraryId"
            }
          }
        },
        "description": "Omit to search the whole 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_-]+$"
      },
      "LibraryId": {
        "type": "string",
        "pattern": "^lib_[A-Za-z0-9_-]+$"
      },
      "ExecutionPolicy": {
        "type": "string",
        "enum": [
          "local_only",
          "prefer_local",
          "cloud_allowed",
          "cloud_required"
        ]
      }
    }
  }
}