Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: 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_MetadataFiltersFiltersItems:
oneOf:
- $ref: '#/components/schemas/search_BooleanEqualsClause'
- $ref: '#/components/schemas/search_EqualsClause'
- $ref: '#/components/schemas/search_NotEqualsClause'
- $ref: '#/components/schemas/search_DateTimeRangeInclusiveClause'
title: MetadataFiltersFiltersItems
search_AppApiRoutesSearchV1SchemaSchemaSearchResponseDataItems:
oneOf:
- $ref: '#/components/schemas/search_Image'
- $ref: '#/components/schemas/search_app__api__routes__search__v1__schema__schema__Keyframe'
title: AppApiRoutesSearchV1SchemaSchemaSearchResponseDataItems
search_CelebrityMatchesRequest:
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.
upload_ids:
type: array
items:
type: string
description: List of upload IDs to search for celebrity matches (15-100 items)
required:
- dataset_id
- upload_ids
description: Celebrity matches request - searches for celebrity matches using a list of upload IDs
title: CelebrityMatchesRequest
search_BooleanEqualsClause:
type: object
properties:
key:
type: string
operator:
type: string
enum:
- ==
value:
type: boolean
required:
- key
- operator
- value
title: BooleanEqualsClause
search_ImageSearchRequest:
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.
coactive_image_id:
type:
- string
- 'null'
format: uuid
description: The image to search for represented with a CID
public_url:
type:
- string
- 'null'
description: The image to search for represented with a public http url
upload_id:
type:
- string
- 'null'
description: The upload ID to search for
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
description: Image search request. Either CID or public_url must be provided.
title: ImageSearchRequest
search_TextSearchByPersonResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/search_ImageResult'
description: The search results matching the person filter
videos:
type: array
items:
$ref: '#/components/schemas/search_TextSearchByPersonVideoResult'
description: Search results aggregated by video, ordered by best matching keyframe score
required:
- data
description: Response for person-filtered text-to-image search
title: TextSearchByPersonResponse
search_ValidationError:
type: object
properties:
loc:
type: array
items:
$ref: '#/components/schemas/search_ValidationErrorLocItems'
msg:
type: string
type:
type: string
required:
- loc
- msg
- type
title: ValidationError
search_NileKeyframe:
type: object
properties:
keyframe_id:
type: string
format: uuid
score:
type: number
format: double
asset_type:
type: string
dataset_id:
type: string
format: uuid
video_id:
type: string
format: uuid
composite_slice_id:
type:
- string
- 'null'
format: uuid
moderation_score:
type:
- number
- 'null'
format: double
required:
- keyframe_id
- score
- asset_type
- dataset_id
- video_id
description: Unit keyframe response from nile
title: NileKeyframe
search_ValidationErrorLocItems:
oneOf:
- type: string
- type: integer
title: ValidationErrorLocItems
search_HybridSearchResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/search_HybridSearchImage'
description: The results from hybrid search
required:
- data
description: Base search response
title: HybridSearchResponse
search_AudioSegment:
type: object
properties:
start_time_ms:
type: integer
description: The start time in milliseconds of the beginning of the audio clip
end_time_ms:
type: integer
description: The end time in milliseconds of the end of the audio clip
speech_to_text_transcription:
type: string
description: The text transcription of the audio clip
required:
- start_time_ms
- end_time_ms
- speech_to_text_transcription
description: Metadata about a video audio segment
title: AudioSegment
search_Shot:
type: object
properties:
shot_id:
type: string
format: uuid
description: The unique shot id
start_time_ms:
type: integer
description: The start time in milliseconds from the beginning of the video
end_time_ms:
type: integer
description: The end time in milliseconds from the beginning of the video
required:
- shot_id
- start_time_ms
- end_time_ms
description: Metadata about a video shot
title: Shot
search_app__api__routes__search__v1__schema__schema__SearchResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/search_AppApiRoutesSearchV1SchemaSchemaSearchResponseDataItems'
description: The paginated results
required:
- data
description: Base search response
title: app__api__routes__search__v1__schema__schema__SearchResponse
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_Image:
type: object
properties:
created_user_id:
type: string
description: The user that created the resource
created_dt:
type: string
format: date-time
description: The created datetime of the resource
updated_user_id:
type: string
description: The user that last updated the resource
updated_dt:
type: string
format: date-time
description: The datetime the resource was last updated
coactive_image_id:
type: string
format: uuid
description: The coactive image id
path:
type:
- string
- 'null'
description: The original path of the image
metadata:
type:
- object
- 'null'
additionalProperties:
description: Any type
description: The user provided metadata for the image
moderation_score:
type:
- number
- 'null'
format: double
description: The moderation score of the image
required:
- created_user_id
- created_dt
- updated_user_id
- updated_dt
- coactive_image_id
description: An image asset response
title: Image
search_Score
# --- 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