openapi: 3.1.0
info:
  title: API Reference agentic-search > agenticSearch API
  version: 1.0.0
servers:
- url: https://api.coactive.ai
  description: Production
- url: https://app.coactive.ai
  description: Production
tags:
- name: agentic-search > agenticSearch
paths:
  /api/v0/chat:
    post:
      operationId: chat
      summary: Chat
      description: Chat endpoint that processes user input with LLM and MCP video search integration for select datasets in the org. Please contact Coactive Support to configure the datasets required.
      tags:
      - agentic-search > agenticSearch
      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/agentic-search:ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agentic-search:HTTPValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentic-search:ChatRequest'
  /api/v0/chat/dataset/{dataset_id}:
    post:
      operationId: chat-dataset
      summary: Chat Dataset
      description: Chat endpoint that processes user input with LLM and MCP video search integration for a specific dataset.
      tags:
      - agentic-search > agenticSearch
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agentic-search:ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agentic-search:HTTPValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agentic-search:ChatRequest'
components:
  schemas:
    agentic-search:VideoSearchResultItem:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
        text_query:
          type: string
        video_id:
          type: string
          format: uuid
        source_path:
          type: string
        video_score:
          type:
          - number
          - 'null'
          format: double
        metadata:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:VideoSearchResultItemMetadata'
          - type: 'null'
        top_composite_slice:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:CompositeSlice'
          - type: 'null'
        top_keyframe:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:VideoKeyframe'
          - type: 'null'
        moderation_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - dataset_id
      - text_query
      - video_id
      - source_path
      description: Single video search result item.
      title: VideoSearchResultItem
    agentic-search:VideoSearchResultItemMetadata:
      oneOf:
      - $ref: '#/components/schemas/agentic-search:VideoMetadata'
      - type: object
        additionalProperties:
          description: Any type
      title: VideoSearchResultItemMetadata
    agentic-search:ToolResult:
      type: object
      properties:
        tool_name:
          $ref: '#/components/schemas/agentic-search:ToolName'
          description: Name of the MCP tool that was invoked
        dataset_id:
          type: string
          format: uuid
          description: ID of the dataset that the tool was invoked for
        dataset_type:
          $ref: '#/components/schemas/agentic-search:DatasetType'
          description: Type of the dataset that the tool was invoked for
        invocation_timestamp:
          type: string
          description: Timestamp of the MCP tool invocation (ISO 8601 format)
        result:
          $ref: '#/components/schemas/agentic-search:ToolResultResult'
          description: Result from the MCP tool invocation
      required:
      - tool_name
      - dataset_id
      - dataset_type
      - invocation_timestamp
      - result
      description: Result from a MCP tool invocation.
      title: ToolResult
    agentic-search:ToolName:
      type: string
      enum:
      - video_search_search_videos
      - video_search_get_video_details
      - apollo_search_image_to_image
      - apollo_search_image_to_keyframes
      - apollo_search_hybrid_search
      - apollo_search_transcript_exact_match
      - apollo_search_audio_search
      - apollo_search_audio_sound_search
      - apollo_search_text_to_image_search_by_person
      - metadata_filter_search_text_to_video_with_metadata_filters
      - metadata_filter_search_text_to_transcript_with_metadata_filters
      - metadata_filter_search_audio_sound_with_metadata_filters
      - metadata_filter_search_text_to_image_with_metadata_filters
      description: Enum of available MCP tool names.
      title: ToolName
    agentic-search:TextToImageSearchByPersonResultItem:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
        asset_type:
          type: string
        dataset_id:
          type: string
          format: uuid
        video_id:
          type:
          - string
          - 'null'
          format: uuid
        composite_slice_id:
          type:
          - string
          - 'null'
          format: uuid
        composite_type:
          type:
          - string
          - 'null'
        composite_start_time_ms:
          type:
          - integer
          - 'null'
        composite_end_time_ms:
          type:
          - integer
          - 'null'
        moderation_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - coactive_image_id
      - asset_type
      - dataset_id
      description: Single result item for text-to-image search by person.
      title: TextToImageSearchByPersonResultItem
    agentic-search:TextToImageSearchByPersonVideoResult:
      type: object
      properties:
        video_id:
          type: string
          format: uuid
        moderation_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - video_id
      description: Video result aggregated from person search results.
      title: TextToImageSearchByPersonVideoResult
    agentic-search:KeyframeSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:KeyframeSearchResultItem'
      description: Response schema for keyframe search tool.
      title: KeyframeSearchResponse
    agentic-search:ValidationErrorLocItems:
      oneOf:
      - type: string
      - type: integer
      title: ValidationErrorLocItems
    agentic-search:CompositeSliceWithScore:
      type: object
      properties:
        id:
          type: string
          format: uuid
        index:
          type:
          - integer
          - 'null'
        start_frame_num:
          type:
          - integer
          - 'null'
        end_frame_num:
          type:
          - integer
          - 'null'
        start_time_ms:
          type:
          - integer
          - 'null'
        end_time_ms:
          type:
          - integer
          - 'null'
        composite_id:
          type:
          - string
          - 'null'
          format: uuid
        composite_type:
          type: string
        composite_slice_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - id
      - composite_type
      description: Composite slice details with drill-down information.
      title: CompositeSliceWithScore
    agentic-search:VideoKeyframe:
      type: object
      properties:
        id:
          type: string
          format: uuid
        frame_time_ms:
          type:
          - integer
          - 'null'
      required:
      - id
      description: Video keyframe details.
      title: VideoKeyframe
    agentic-search:ChatResponse:
      type: object
      properties:
        chat_response_text:
          type: string
          description: LLM response text
        tool_results:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:ToolResult'
          description: 'Results from MCP tools invoked during this request. '
        history_chat_messages:
          type: array
          items:
            type: object
            additionalProperties:
              description: Any type
          description: Conversation history (includes current message)
        suggested_follow_ups:
          type: array
          items:
            type: string
          description: Suggested follow-up messages to continue the conversation
      required:
      - chat_response_text
      - tool_results
      - history_chat_messages
      - suggested_follow_ups
      description: Response schema for chat endpoint.
      title: ChatResponse
    agentic-search:HybridSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:HybridSearchResultItem'
      description: Response schema for hybrid search tool.
      title: HybridSearchResponse
    agentic-search:TranscriptExactMatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:VideoTranscriptMatch'
      description: Response schema for apollo_search_transcript_exact_match tool.
      title: TranscriptExactMatchResponse
    agentic-search:MetadataFilterTriggerResponse:
      type: object
      properties:
        run_id:
          type: integer
      required:
      - run_id
      description: All metadata-filter search tools now return an async job run_id.
      title: MetadataFilterTriggerResponse
    agentic-search:VideoMetadata:
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            description: Any type
      description: Metadata associated with a video.
      title: VideoMetadata
    agentic-search:GetVideoDetailsResponse:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
        text_query:
          type: string
        video_id:
          type: string
          format: uuid
        composite_type:
          type: string
        source_path:
          type: string
        slices:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:CompositeSliceWithScore'
      required:
      - dataset_id
      - text_query
      - video_id
      - composite_type
      - source_path
      description: Response schema for get_video_details tool.
      title: GetVideoDetailsResponse
    agentic-search:VideoSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:VideoSearchResultItem'
      description: Response schema for search_videos tool.
      title: VideoSearchResponse
    agentic-search:AudioChunk:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
        video:
          $ref: '#/components/schemas/agentic-search:Video'
        start_time_ms:
          type: integer
        end_time_ms:
          type: integer
        score:
          type: number
          format: double
        timestamp:
          type:
          - integer
          - 'null'
        moderation_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - coactive_image_id
      - video
      - start_time_ms
      - end_time_ms
      - score
      description: A single audio chunk result.
      title: AudioChunk
    agentic-search:Shot:
      type: object
      properties:
        shot_id:
          type: string
          format: uuid
        start_time_ms:
          type: integer
        end_time_ms:
          type: integer
      required:
      - shot_id
      - start_time_ms
      - end_time_ms
      description: Metadata about a video shot.
      title: Shot
    agentic-search:TextToImageSearchByPersonResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:TextToImageSearchByPersonResultItem'
        videos:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:TextToImageSearchByPersonVideoResult'
      description: Response schema for text_to_image_search_by_person tool.
      title: TextToImageSearchByPersonResponse
    agentic-search:KeyframeSearchResultItem:
      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: Single keyframe search result item.
      title: KeyframeSearchResultItem
    agentic-search:HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:ValidationError'
      title: HTTPValidationError
    agentic-search:HybridSearchResultItem:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
        path:
          type:
          - string
          - 'null'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        moderation_score:
          type:
          - number
          - 'null'
          format: double
        relevance_score:
          type: number
          format: double
      required:
      - coactive_image_id
      - relevance_score
      description: Single hybrid search result item.
      title: HybridSearchResultItem
    agentic-search:ChatRequest:
      type: object
      properties:
        chat_request_text:
          type:
          - string
          - 'null'
          description: User's chat input text
        upload_id:
          type:
          - string
          - 'null'
          description: Upload ID of the user's input image
        history_chat_messages:
          type:
          - array
          - 'null'
          items:
            type: object
            additionalProperties:
              description: Any type
          description: Conversation history (does not include current message)
      description: Request schema for chat endpoint.
      title: ChatRequest
    agentic-search:AudioSegment:
      type: object
      properties:
        start_time_ms:
          type: integer
        end_time_ms:
          type: integer
        speech_to_text_transcription:
          type: string
      required:
      - start_time_ms
      - end_time_ms
      - speech_to_text_transcription
      description: Metadata about a video audio segment.
      title: AudioSegment
    agentic-search:CompositeSlice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        index:
          type:
          - integer
          - 'null'
        start_frame_num:
          type:
          - integer
          - 'null'
        end_frame_num:
          type:
          - integer
          - 'null'
        start_time_ms:
          type:
          - integer
          - 'null'
        end_time_ms:
          type:
          - integer
          - 'null'
        composite_id:
          type:
          - string
          - 'null'
          format: uuid
        composite_type:
          type: string
      required:
      - id
      - composite_type
      description: Composite slice details (used by both video search and transcript matching).
      title: CompositeSlice
    agentic-search:AudioSoundSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:AudioChunk'
      description: Response schema for apollo_search_audio_sound_search tool.
      title: AudioSoundSearchResponse
    agentic-search:DatasetType:
      type: string
      enum:
      - native_video
      - legacy
      description: Dataset type enum.
      title: DatasetType
    agentic-search:ImageKeyframeSearchResultItem:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
        path:
          type:
          - string
          - 'null'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        moderation_score:
          type:
          - number
          - 'null'
          format: double
        video:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:Video'
          - type: 'null'
        shot:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:Shot'
          - type: 'null'
        audio_segment:
          oneOf:
          - $ref: '#/components/schemas/agentic-search:AudioSegment'
          - type: 'null'
        timestamp:
          type:
          - integer
          - 'null'
      required:
      - coactive_image_id
      description: Base result item with common fields for image and keyframe search results.
      title: ImageKeyframeSearchResultItem
    agentic-search:ImageKeyframeSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:ImageKeyframeSearchResultItem'
      description: Response schema for image and keyframe search tools.
      title: ImageKeyframeSearchResponse
    agentic-search:Video:
      type: object
      properties:
        coactive_video_id:
          type: string
          format: uuid
        path:
          type:
          - string
          - 'null'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
      required:
      - coactive_video_id
      description: Video asset metadata.
      title: Video
    agentic-search:ToolResultResult:
      oneOf:
      - $ref: '#/components/schemas/agentic-search:VideoSearchResponse'
      - $ref: '#/components/schemas/agentic-search:ImageKeyframeSearchResponse'
      - $ref: '#/components/schemas/agentic-search:KeyframeSearchResponse'
      - $ref: '#/components/schemas/agentic-search:TranscriptExactMatchResponse'
      - $ref: '#/components/schemas/agentic-search:HybridSearchResponse'
      - $ref: '#/components/schemas/agentic-search:GetVideoDetailsResponse'
      - $ref: '#/components/schemas/agentic-search:TextToImageSearchByPersonResponse'
      - $ref: '#/components/schemas/agentic-search:MetadataFilterTriggerResponse'
      - $ref: '#/components/schemas/agentic-search:AudioSoundSearchResponse'
      description: Result from the MCP tool invocation
      title: ToolResultResult
    agentic-search:VideoTranscriptMatch:
      type: object
      properties:
        coactive_image_id:
          type: string
          format: uuid
        video:
          $ref: '#/components/schemas/agentic-search:Video'
        audio_segment:
          $ref: '#/components/schemas/agentic-search:AudioSegment'
        coverage_score:
          type:
          - number
          - 'null'
          format: double
        timestamp:
          type:
          - integer
          - 'null'
        moderation_score:
          type:
          - number
          - 'null'
          format: double
      required:
      - coactive_image_id
      - video
      - audio_segment
      description: A single transcript match result with keyframe and slice information.
      title: VideoTranscriptMatch
    agentic-search:ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/agentic-search:ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer