openapi: 3.1.0
info:
title: API Reference agentic-search > agenticSearch search > search API
version: 1.0.0
servers:
- url: https://api.coactive.ai
description: Production
- url: https://app.coactive.ai
description: Production
tags:
- name: search > search
paths:
/api/v1/search/audio:
post:
operationId: audio-search
summary: Audio Search
description: Find video segments where the spoken content matches a natural-language query. Use this to find moments by what was said, for example, thank you for your time or breaking news.Returns matching audio segments with the parent video, the transcript text, and timestamps so you can jump straight to the moment.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:app__api__routes__search__v1__schema__native_video_model_schema__SearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:AudioSearchRequest'
/api/v1/search/audio-sound:
post:
operationId: audio-sound-search
summary: Audio Sounds Search
description: Find video segments containing a specific audio sound class, for example, Music, Dog, gunfire, or clapping.Returns ranked segments with timestamps and a confidence score.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:AudioSoundSearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:AudioSoundSearchRequest'
/api/v1/search/celebrity/matches:
post:
operationId: celebrity-matches-api-v-1-search-celebrity-matches-post
summary: Celebrity Matches Search
description: Find video frames that match a reference set of face images.Provide 15–100 upload IDs of reference images and get back ranked keyframe matches across the dataset's videos.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:NileSearchKeyframeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:CelebrityMatchesRequest'
/api/v1/search/text-to-hybrid-search:
post:
operationId: hybrid-search
summary: Hybrid Search
description: Search images using a text query that scores results against both visual content and text metadata (titles, captions, descriptions, and other text fields).This endpoint is in beta and requires special access, please contact the support team.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:HybridSearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:HybridSearchRequest'
/api/v1/search/image-to-image:
post:
operationId: image-to-image
summary: Image to Image Search
description: Find visually similar images using a reference image. Provide the reference as either a coactive_image_id (an asset already in the dataset) or a public_url.Useful for finding visually related assets.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:app__api__routes__search__v1__schema__schema__SearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:ImageSearchRequest'
/api/v1/search/image-to-keyframes:
post:
operationId: image-to-keyframes
summary: Image to Keyframes Search
description: Find video keyframes that look similar to a reference image. Provide the reference as a public_url or upload_id.Returns a ranked list of matching frames with their parent video.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:NileSearchKeyframeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:ImageToKeyframeSearchRequest'
/api/v1/search/text-to-image/by-person:
post:
operationId: text-to-image-search-by-person
summary: Text to Image by Person Search
description: Search for video keyframes that match a text query and contain a specific enrolled person — for example, Jane Doe at a press conference. Specify the person via either person_ids or person_names_or_aliases.The person must already be enrolled in your organization. Returns matching assets plus a video-level list aggregated by best matching keyframe score.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:TextSearchByPersonResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:TextSearchByPersonRequest'
/api/v1/search/text-to-image:
post:
operationId: text-search-api-v-1-search-text-to-image-post
summary: Text to Image Search
description: Search a dataset with a natural-language query and get back the images that best match it. Use this when you want to find visuals by describing what's in them.For example, search for a sunset at the beach or Jalen Hurts holding the Vince Lombardi trophy. Pair the text query with exact-match metadata filters to narrow results further.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:app__api__routes__search__v1__schema__schema__SearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:TextSearchRequest'
/api/v1/search/text-to-keyframes:
post:
operationId: text-to-keyframes-search-api-v-1-search-text-to-keyframes-post
summary: Text to Keyframes Search
description: Search across all video frames in a dataset using a natural-language query. Returns the keyframes that best match the description.Use this when you want all the keyframe-level results from your videos rather than one-result-per-video.
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:NileSearchKeyframeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:TextSearchRequest'
/api/v1/search/text-to-transcript/exact-match:
post:
operationId: transcript-exact-match
summary: Transcript Exact Match
description: Performs an exact text match search on video transcripts using a natural language text query (e.g., 'thank you for your time' or 'my name is John') within a specified dataset (dataset_id). This searches for exact occurrences of the provided text within video transcript data, not semantic or approximate matching. Returns videos grouped by their exact transcript matches, where each match includes the composite slice (shot or scene) containing the match, the matched transcript text, timestamps, frame numbers, and a coverage score indicating how much of the composite's transcript is covered by the query (1.0 means the query matches the entire transcript).
tags:
- search > search
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/search:TranscriptTextMatchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/search:HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/search:TranscriptMatchRequest'
components:
schemas:
search:AppApiRoutesSearchV1SchemaNativeVideoModelSchemaSearchResponseDataItems:
oneOf:
- $ref: '#/components/schemas/search:Image'
- $ref: '#/components/schemas/search:app__api__routes__search__v1__schema__native_video_model_schema__Keyframe'
title: AppApiRoutesSearchV1SchemaNativeVideoModelSchemaSearchResponseDataItems
search:app__api__routes__search__v1__schema__schema__Keyframe:
type: object
properties:
coactive_image_id:
type: string
format: uuid
description: The coactive image id
video:
$ref: '#/components/schemas/search:Video'
description: The video the keyframe belongs to
shot:
$ref: '#/components/schemas/search:Shot'
description: The video shot metadata
audio_segment:
oneOf:
- $ref: '#/components/schemas/search:AudioSegment'
- type: 'null'
description: Audio segment associated with the keyframe (if the asset_type is 'keyframe')
timestamp:
type:
- integer
- 'null'
description: The timestamp of the keyframe in the video in milliseconds
moderation_score:
type:
- number
- 'null'
format: double
description: The moderation score of the image
keyframe_is_v1:
type: boolean
default: false
description: Whether the keyframe is from the v1 video data model
required:
- coactive_image_id
- video
- shot
description: A keyframe asset response
title: app__api__routes__search__v1__schema__schema__Keyframe
search:TextSearchByPersonVideoResult:
type: object
properties:
video_id:
type: string
format: uuid
description: The unique identifier of the video
moderation_score:
type:
- number
- 'null'
format: double
description: The moderation score of the video
required:
- video_id
description: Video result with grouped keyframes for person-filtered text-to-image search
title: TextSearchByPersonVideoResult
search:AudioClass:
type: string
enum:
- Speech
- Male speech, man speaking
- Female speech, woman speaking
- Child speech, kid speaking
- Conversation
- Narration, monologue
- Babbling
- Speech synthesizer
- Shout
- Bellow
- Whoop
- Yell
- Battle cry
- Children shouting
- Screaming
- Whispering
- Laughter
- Baby laughter
- Giggle
- Snicker
- Belly laugh
- Chuckle, chortle
- Crying, sobbing
- Baby cry, infant cry
- Whimper
- Wail, moan
- Sigh
- Singing
- Choir
- Yodeling
- Chant
- Mantra
- Male singing
- Female singing
- Child singing
- Synthetic singing
- Rapping
- Humming
- Groan
- Grunt
- Whistling
- Breathing
- Wheeze
- Snoring
- Gasp
- Pant
- Snort
- Cough
- Throat clearing
- Sneeze
- Sniff
- Run
- Shuffle
- Walk, footsteps
- Chewing, mastication
- Biting
- Gargling
- Stomach rumble
- Burping, eructation
- Hiccup
- Fart
- Hands
- Finger snapping
- Clapping
- Heart sounds, heartbeat
- Heart murmur
- Cheering
- Applause
- Chatter
- Crowd
- Hubbub, speech noise, speech babble
- Children playing
- Animal
- Domestic animals, pets
- Dog
- Bark
- Yip
- Howl
- Bow-wow
- Growling
- Whimper (dog)
- Cat
- Purr
- Meow
- Hiss
- Caterwaul
- Livestock, farm animals, working animals
- Horse
- Clip-clop
- Neigh, whinny
- Cattle, bovinae
- Moo
- Cowbell
- Pig
- Oink
- Goat
- Bleat
- Sheep
- Fowl
- Chicken, rooster
- Cluck
- Crowing, cock-a-doodle-doo
- Turkey
- Gobble
- Duck
- Quack
- Goose
- Honk
- Wild animals
- Roaring cats (lions, tigers)
- Roar
- Bird
- Bird vocalization, bird call, bird song
- Chirp, tweet
- Squawk
- Pigeon, dove
- Coo
- Crow
- Caw
- Owl
- Hoot
- Bird flight, flapping wings
- Canidae, dogs, wolves
- Rodents, rats, mice
- Mouse
- Patter
- Insect
- Cricket
- Mosquito
- Fly, housefly
- Buzz
- Bee, wasp, etc.
- Frog
- Croak
- Snake
- Rattle
- Whale vocalization
- Music
- Musical instrument
- Plucked string instrument
- Guitar
- Electric guitar
- Bass guitar
- Acoustic guitar
- Steel guitar, slide guitar
- Tapping (guitar technique)
- Strum
- Banjo
- Sitar
- Mandolin
- Zither
- Ukulele
- Keyboard (musical)
- Piano
- Electric piano
- Organ
- Electronic organ
- Hammond organ
- Synthesizer
- Sampler
- Harpsichord
- Percussion
- Drum kit
- Drum machine
- Drum
- Snare drum
- Rimshot
- Drum roll
- Bass drum
- Timpani
- Tabla
- Cymbal
- Hi-hat
- Wood block
- Tambourine
- Rattle (instrument)
- Maraca
- Gong
- Tubular bells
- Mallet percussion
- Marimba, xylophone
- Glockenspiel
- Vibraphone
- Steelpan
- Orchestra
- Brass instrument
- French horn
- Trumpet
- Trombone
- Bowed string instrument
- String section
- Violin, fiddle
- Pizzicato
- Cello
- Double bass
- Wind instrument, woodwind instrument
- Flute
- Saxophone
- Clarinet
- Harp
- Bell
- Church bell
- Jingle bell
- Bicycle bell
- Tuning fork
- Chime
- Wind chime
- Change ringing (campanology)
- Harmonica
- Accordion
- Bagpipes
- Didgeridoo
- Shofar
- Theremin
- Singing bowl
- Scratching (performance technique)
- Pop music
- Hip hop music
- Beatboxing
- Rock music
- Heavy metal
- Punk rock
- Grunge
- Progressive rock
- Rock and roll
- Psychedelic rock
- Rhythm and blues
- Soul music
- Reggae
- Country
- Swing music
- Bluegrass
- Funk
- Folk music
- Middle Eastern music
- Jazz
- Disco
- Classical music
- Opera
- Electronic music
- House music
- Techno
- Dubstep
- Drum and bass
- Electronica
- Electronic dance music
- Ambient music
- Trance music
- Music of Latin America
- Salsa music
- Flamenco
- Blues
- Music for children
- New-age music
- Vocal music
- A capella
- Music of Africa
- Afrobeat
- Christian music
- Gospel music
- Music of Asia
- Carnatic music
- Music of Bollywood
- Ska
- Traditional music
- Independent music
- Song
- Background music
- Theme music
- Jingle (music)
- Soundtrack music
- Lullaby
- Video game music
- Christmas music
- Dance music
- Wedding music
- Happy music
- Funny music
- Sad music
- Tender music
- Exciting music
- Angry music
- Scary music
- Wind
- Rustling leaves
- Wind noise (microphone)
- Thunderstorm
- Thunder
- Water
- Rain
- Raindrop
- Rain on surface
- Stream
- Waterfall
- Ocean
- Waves, surf
- Steam
- Gurgling
- Fire
- Crackle
- Vehicle
- Boat, Water vehicle
- Sailboat, sailing ship
- Rowboat, canoe, kayak
- Motorboat, speedboat
- Ship
- Motor vehicle (road)
- Car
- Vehicle horn, car horn, honking
- Toot
- Car alarm
- Power windows, electric windows
- Skidding
- Tire squeal
- Car passing by
- Race car, auto racing
- Truck
- Air brake
- Air horn, truck horn
- Reversing beeps
- Ice cream truck, ice cream van
- Bus
- Emergency vehicle
- Police car (siren)
- Ambulance (siren)
- Fire engine, fire truck (siren)
- Motorcycle
- Traffic noise, roadway noise
- Rail transport
- Train
- Train whistle
- Train horn
- Railroad car, train wagon
- Train wheels squealing
- Subway, metro, underground
- Aircraft
- Aircraft engine
- Jet engine
- Propeller, airscrew
- Helicopter
- Fixed-wing aircraft, airplane
- Bicycle
- Skateboard
- Engine
- Light engine (high frequency)
- Dental drill, dentist's drill
- Lawn mower
- Chainsaw
- Medium engine (mid frequency)
- Heavy engine (low frequency)
- Engine knocking
- Engine starting
- Idling
- Accelerating, revving, vroom
- Door
- Doorbell
- Ding-dong
- Sliding door
- Slam
- Knock
- Tap
- Squeak
- Cupboard open or close
- Drawer open or close
- Dishes, pots, and pans
- Cutlery, silverware
- Chopping (food)
- Frying (food)
- Microwave oven
- Blender
- Water tap, faucet
- Sink (filling or washing)
- Bathtub (filling or washing)
- Hair dryer
- Toilet flush
- Toothbrush
- Electric toothbrush
- Vacuum cleaner
- Zipper (clothing)
- Keys jangling
- Coin (dropping)
- Scissors
- Electric shaver, electric razor
- Shuffling cards
- Typing
- Typewriter
- Computer keyboard
- Writing
- Alarm
- Telephone
- Telephone bell ringing
- Ringtone
- Telephone dialing, DTMF
- Dial tone
- Busy signal
- Alarm clock
- Siren
- Civil defense siren
- Buzzer
- Smoke detector, smoke alarm
- Fire alarm
- Foghorn
- Whistle
- Steam whistle
- Mechanisms
- Ratchet, pawl
- Clock
- Tick
- Tick-tock
- Gears
- Pulleys
- Sewing machine
- Mechanical fan
- Air conditioning
- Cash register
- Printer
- Camera
- Single-lens reflex camera
- Tools
- Hammer
- Jackhammer
- Sawing
- Filing (rasp)
- Sanding
- Power tool
- Drill
- Explosion
- Gunshot, gunfire
- Machine gun
- Fusillade
- Artillery fire
- Cap gun
- Fireworks
- Firecracker
- Burst, pop
- Eruption
- Boom
- Wood
- Chop
- Splinter
- Crack
- Glass
- Chink, clink
- Shatter
- Liquid
- Splash, splatter
- Slosh
- Squish
- Drip
- Pour
- Trickle, dribble
- Gush
- Fill (with liquid)
- Spray
- Pump (liquid)
- Stir
- Boiling
- Sonar
- Arrow
- Whoosh, swoosh, swish
- Thump, thud
- Thunk
- Electronic tuner
- Effects unit
- Chorus effect
- Basketball bounce
- Bang
- Slap, smack
- Whack, thwack
- Smash, crash
- Breaking
- Bouncing
- Whip
- Flap
- Scratch
- Scrape
- Rub
- Roll
- Crushing
- Crumpling, crinkling
- Tearing
- Beep, bleep
- Ping
- Ding
- Clang
- Squeal
- Creak
- Rustle
- Whir
- Clatter
- Sizzle
- Clicking
- Clickety-clack
- Rumble
- Plop
- Jingle, tinkle
- Hum
- Zing
- Boing
- Crunch
- Silence
- Sine wave
- Harmonic
- Chirp tone
- Sound effect
- Pulse
- Inside, small room
- Inside, large room or hall
- Inside, public space
- Outside, urban or manmade
- Outside, rural or natural
- Reverberation
- Echo
- Noise
- Environmental noise
- Static
- Mains hum
- Distortion
- Sidetone
- Cacophony
- White noise
- Pink noise
- Throbbing
- Vibration
- Television
- Radio
- Field recording
description: AudioSet audio class labels (527 classes)
title: AudioClass
search:AudioSearchRequest:
type: object
properties:
dataset_id:
type: string
format: uuid
description: The unique identifier for the dataset
offset:
type: integer
default: 0
description: Starting index to return
limit:
type: integer
default: 100
description: Max number of items to return
metadata_filters:
oneOf:
- $ref: '#/components/schemas/search:MetadataFilters'
- type: 'null'
description: List of metadata filters to apply to the search
moderation_score_type:
$ref: '#/components/schemas/search:ScoreType'
description: Type of moderation scores to return when moderation is enabled.probability returns scores 0-1 using BGE Reranker model.level returns scores 0-5 using OpenAI model.This does not enable/disable moderation - use skip_moderation for that.
text_query:
type: string
description: The text query to search for
skip_moderation:
type: boolean
default: false
description: Skip content moderation if enabled
required:
- dataset_id
- text_query
description: Audio search request
title: AudioSearchRequest
search:app__api__routes__search__v1__schema__native_video_model_schema__Keyframe:
type: object
properties:
coactive_image_id:
type: string
format: uuid
description: The coactive image id
video:
$ref: '#/components/schemas/search:Video'
description: The video that this keyframe belongs to
audio_segment:
oneOf:
- $ref: '#/components/schemas/search:AudioSegment'
- type: 'null'
description: The audio segment associated with this keyframe
timestamp:
type:
- integer
- 'null'
description: The timestamp in milliseconds of the keyframe in the video
moderation_score:
type:
- number
- 'null'
format: double
description: The moderation score of the image
required:
- coactive_image_id
- video
description: A keyframe asset response for native video model datasets (without shot metadata)
title: app__api__routes__search__v1__schema__native_video_model_schema__Keyframe
search:NileSearchKeyframeResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/search:NileKeyframe'
required:
- data
description: A keyframe asset response from Nile for text to keyframe search
title: NileSearchKeyframeResponse
search:TranscriptMatchRequest:
type: object
properties:
dataset_id:
type: string
format: uuid
description: The unique identifier for the dataset
offset:
type: integer
default: 0
description: Starting index to return
limit:
type: integer
default: 100
description: Max number of items to return
metadata_filters:
oneOf:
- $ref: '#/components/schemas/search:MetadataFilters'
- type: 'null'
description: List of metadata filters to apply to the search
moderation_score_type:
$ref: '#/components/schemas/search:ScoreType'
description: Type of moderation scores to return when moderation is enabled.probability returns scores 0-1 using BGE Reranker model.level returns scores 0-5 using OpenAI model.This does not enable/disable moderation - use skip_moderation for that.
text_query:
type: string
description: The text query to search for
composite_type:
type:
- string
- 'null'
default: shot
description: The composite type to query on.
required:
- dataset_id
- text_query
description: Transcript Match Request
title: TranscriptMatchRequest
search:CompositeType:
type: string
enum:
- shot
- scene
- segment
description: Type of composite for video keyframes
title: CompositeType
search:NotEqualsClause:
type: object
properties:
key:
type: string
operator:
type: string
enum:
- '!='
value:
type: string
required:
- key
- operator
- value
title: NotEqualsClause
search:TextSearchRequest:
type: object
properties:
dataset_id:
type: string
format: uuid
description: The unique identifier for the dataset
offset:
type: integer
default: 0
description: Starting index to return
limit:
type: integer
default: 100
description: Max number of items to return
metadata_filters:
oneOf:
- $ref: '#/components/schemas/search:MetadataFilters'
- type: 'null'
description: List of metadata filters to apply to the search
moderation_score_type:
$ref: '#/components/schemas/search:ScoreType'
description: Type of moderation scores to return when moderation is enabled.probability returns scores 0-1 using BGE Reranker model.level returns scores 0-5 using OpenAI model.This does not enable/disable moderation - use skip_moderation for that.
text_query:
type: string
description: The text query to search for
negative_text:
type:
- string
- 'null'
description: Optional text describing what to exclude from search results. Steers the query embedding away from this direction.
asset_type:
oneOf:
- $ref: '#/components/schemas/search:AssetType'
- type: 'null'
description: The asset type to filter results by. If no asset type is selected the endpoint will search over images and videos
skip_moderation:
type: boolean
default: false
description: Skip content moderation if enabled
required:
- dataset_id
- text_query
description: Text search request
title: TextSearchRequest
search:ImageToKeyframeSearchRequest:
type: object
properties:
dataset_id:
type: string
format: uuid
description: The unique identifier for the dataset
offset:
type: integer
default: 0
description: Starting index to return
limit:
type: integer
default: 100
description: Max number of items to return
metadata_filters:
oneOf:
- $ref: '#/components/schemas/search:MetadataFilters'
- type: 'null'
description: List of metadata filters to apply to the search
moderation_score_type:
$ref: '#/components/schemas/search:ScoreType'
description: Type of moderation scores to return when moderation is enabled.pro
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coactive/refs/heads/main/openapi/coactive-search-search-api-openapi.yml