Coactive AI search > search API

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:ImageResult:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
          description: The unique identifier of the image/keyframe
        asset_type:
          $ref: '#/components/schemas/search:VisualAssetType'
          description: The type of asset ('image' or 'keyframe')
        dataset_id:
          type: string
          format: uuid
          description: The dataset identifier this asset belongs to
        video_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The video identifier (for video keyframes only)
        composite_slice_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The composite slice identifier (for video keyframes only)
        composite_type:
          oneOf:
          - $ref: '#/components/schemas/search:CompositeType'
          - type: 'null'
          description: The type of composite (for video keyframes only)
        composite_start_time_ms:
          type:
          - integer
          - 'null'
          description: The start time of the composite slice in milliseconds (for video keyframes only)
        composite_end_time_ms:
          type:
          - integer
          - 'null'
          description: The end time of the composite slice in milliseconds (for video keyframes only)
        moderation_score:
          type:
          - number
          - 'null'
          format: double
          description: The moderation score of the asset (if applicable)
      required:
      - coactive_image_id
      - asset_type
      - dataset_id
      description: Unified search result for person-filtered text-to-image search
      title: ImageResult
    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.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
        public_url:
          type:
          - string
          - 'null'
        upload_id:
          type:
          - string
          - 'null'
        skip_moderation:
          type: boolean
          default: false
          description: Skip content moderation if enabled
      required:
      - dataset_id
      description: Image to keyframe search request
      title: ImageToKeyframeSearchRequest
    search:VideoTranscriptMatch:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
          description: The coactive image id of the keyframe closest to the transcript match
        video:
          $ref: '#/components/schemas/search:Video'
          description: The video that this transcript match belongs to
        audio_segment:
          $ref: '#/components/schemas/search:AudioSegment'
          description: The audio segment associated with this transcript match
        coverage_score:
          type:
          - number
          - 'null'
          format: double
          description: Coverage score for this transcript match. i.e How much of composite transcript is covered by the query text
        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 video
      required:
      - coactive_image_id
      - video
      - audio_segment
      description: A single transcript match result with keyframe and slice information
      title: VideoTranscriptMatch
    search:TextSearchByPersonRequest:
      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.
        person_ids:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: List of person IDs to filter results by. Currently only a single person_id is supported.
        person_names_or_aliases:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of person names/aliases to filter results by. Currently only a single person name is supported.
        asset_type:
          $ref: '#/components/schemas/search:VisualAssetType'
          description: Visual asset type to search over. For datasets using the native video data model, only 'keyframe' is supported.
        skip_moderation:
          type: boolean
          default: false
          description: Skip content moderation if enabled
      required:
      - dataset_id
      - text_query
      - asset_type
      description: Text search filtered by person request
      title: TextSearchByPersonRequest
    search:HybridSearchImage:
      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
        relevance_score:
          type: number
          format: double
          description: The relevance score of the image
      required:
      - created_user_id
      - created_dt
      - updated_user_id
      - updated_dt
      - coactive_image_id
      - relevance_score
      description: An image asset response
      title: HybridSearchImage
    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:TranscriptTextMatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/search:VideoTranscriptMatch'
          description: List of individual transcript matches with their corresponding keyframes
      required:
      - data
      description: Native video model search response for exact transcript text match
      title: TranscriptTextMatchResponse
    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:VisualAssetType:
      type: string
      enum:
      - image
      - keyframe
      title: VisualAssetType
    search:MetadataFilters:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/search:MetadataFiltersFiltersItems'
      required:
      - filters
      title: MetadataFilters
    search:AudioChunk:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
          description: The coactive image id of the keyframe closest to the audio chunk
        video:
          $ref: '#/components/schemas/search:Video'
          description: The video that this audio chunk belongs to
        start_time_ms:
          type: integer
          description: The start time in milliseconds of the beginning of the audio chunk
        end_time_ms:
          type: integer
          description: The end time in milliseconds of the end of the audio chunk
        score:
          type: number
          format: double
          description: Confidence score of this audio chunk for the audio class
        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 video
      required:
      - coactive_image_id
      - video
      - start_time_ms
      - end_time_ms
      - score
      description: A single audio chunk result
      title: AudioChunk
    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:HybridSearchRequest:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
          description: The unique identifier for the dataset
        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 visual query embedding away from this direction.
        limit:
          type: integer
          default: 100
          description: Max number of items to return from hybrid search
        datetime_filter:
          oneOf:
          - $ref: '#/components/schemas/search:DateTimeRangeInclusiveClause'
          - type: 'null'
          description: Filter results to only include items with timestamps within this datetime range
        skip_moderation:
          type: boolean
          default: false
          description: Skip content moderation if enabled
        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.
      required:
      - dataset_id
      - text_query
      description: Hybrid search request
      title: HybridSearchRequest
    search:HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/search:ValidationError'
      title: HTTPValidationError
    search:ValidationErrorLocItems:
      oneOf:
      - type: string
      - type: integer
      title: ValidationErrorLocItems
    search:AudioSoundSearchRequest:
      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.
        audio_class:
          $ref: '#/components/schemas/search:AudioClass'
          description: The audio class to search for
        skip_moderation:
          type: boolean
          default: false
          description: Skip content moderation if enabled
      required:
      - dataset_id
      - audio_class
      description: Audio sound search request
      title: AudioSoundSearchRequest
    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:AppApiRoutesSearchV1SchemaSchemaSearchR

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coactive-ai/refs/heads/main/openapi/coactive-ai-search-search-api-openapi.yml