Search indexed videos

POST/api/v1alpha1/search

Searches your indexed videos with a natural-language query and returns ranked matches, each with a score and, where one exists, a media URL you can play back.

Access: an alpha-enabled API key with the SEARCH_CONTENT permission.
Scope: pass video_ids to search only those videos. If any id is not visible to your workspace, the whole request returns 404.
Tuning: limit defaults to 25 and accepts 1-100. threshold defaults to 0.7 and accepts 0-1.

Take a video_id from the results to GET /api/v1alpha1/videos/{video_id} for its processing state, or open the media URLs to review the match.

Authorization

apiKey

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

limit?number

Maximum number of ranked results to return. The default is 25 and the accepted range is 1-100.

Formatint32

Range1 <= value <= 100

Default25

query*string

Natural-language query matched against indexed video evidence.

Lengthlength <= 2000

threshold?number

Minimum similarity score accepted for a result. The default is 0.7 and the accepted range is 0-1.

Range0 <= value <= 1

Default0.7

video_ids?array<string>

Restrict search to video identifiers owned by the authenticated API key workspace. Every requested id must be visible.

Itemsitems <= 100

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1alpha1/search" \  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "limit": 10,    "query": "person entering through the north door",    "threshold": 0.82,    "video_ids": [      "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"    ]  }'

{  "data": [    {      "id": "vid_0190b5d4_frame_0042",      "image": "https://cdn.example.test/media/vid_0190b5d4/frame-0042.jpg",      "scene_description": "A person enters through the north door.",      "score": 0.94,      "tags": [        "person",        "north door"      ],      "time_position": 222000,      "title": "warehouse-inspection-2026-08-08.mp4",      "video_id": "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",      "video_url": "https://cdn.example.test/media/vid_0190b5d4/video.mp4"    }  ],  "has_more": false,  "next_cursor": "MDEyMzQ1Njc4OWFitSLKnTQIcJAwDPi07V5EGs76Im3F8rCuUshrBnHuUJY7_8Ie8Stea_TKuhKhDw5XkRdkBI3IKkvsKT9Kp60Wpx7CoTCGQW8FnalDILVbuy8wxvWWf_B8SA"}

Authorization

Request Body

Response Body

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`