---
title: "Search Assets"
method: POST
path: "/tools/search/assets"
tags: ["accepts-api-key"]
---

# Search Assets

`POST /tools/search/assets`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/tools/search/assets`
- Auth: none declared

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Request body

- SearchAssetsRequest
  - `prompt` string, required: Natural language query to search for.
  - `search_mode` 'semantic_by_scene_keyframe' | 'semantic_by_scene_description' | 'semantic_by_scene_sequence' | 'semantic_by_asset_description' | 'text_by_filename' | 'text_by_file_description': Search mode. Semantic modes are embedding-based, not keyword matching. semantic_by_scene_keyframe matches on keyframe embeddings, semantic_by_scene_description on single-scene description embeddings, and semantic_by_scene_sequence on aggregate consecutive-scene embeddings. text_by_filename searches filenames by case-insensitive substring, and text_by_file_description searches asset descriptions by case-insensitive substring.
  - `folder` string, nullable: Folder path to restrict the search to (e.g. '/my-project').
  - `file_type` 'video' | 'audio' | 'image' | 'text' | 'pdf' | 'lut' | 'font' | 'placeholder' | 'group_clip' | 'master_clip' | 'aaf' | 'proj_original' | 'folder' | 'project' | 'entity' | 'teller_config'
  - `format` '16:9' | '9:16', nullable: Filter by aspect ratio.
  - `only_my_files` boolean: Search only your own library, leaving out files shared with you (directly or through a group) and public ones.
  - `limit` integer: Number of results.
  - `cursor` string, nullable: Opaque cursor returned by a previous page.

## Response `200`

Successful Response

- SearchAssetsResponse
  - `results` AssetSearchResult[], required
    - `asset_id` string, required
    - `score` number, required
    - `description` string, required
    - `start_time_seconds` number, required
    - `end_time_seconds` number, required
  - `next_cursor` string, nullable

## Other responses

- `402`: Not enough Tellers tokens to run this tool. The call was refused before the tool ran, so nothing was charged. Buy more tokens or wait for the next subscription grant.
- `403`: The account's email is not verified yet, so it cannot spend tokens. Nothing was charged. `detail.code` is `EMAIL_NOT_VERIFIED`.
- `422`: Validation Error

---

[API](https://skmtc.dev/tellers/apis/tellers-api.md) - [All operations](https://skmtc.dev/tellers/apis/tellers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tellers/apis/tellers-api/revisions/fdaa0fa44a26?raw)