Typesense Conversational Search API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events Conversational Search API
  description: The Typesense Analytics API allows developers to track and analyze search behavior by recording click, conversion, and visit events. It provides endpoints for creating analytics rules, logging events with metadata tags, and retrieving popular queries and queries with no results. This data can be used to improve search relevance through query suggestions, curations, and understanding user search patterns.
  version: '30.1'
  contact:
    name: Typesense Support
    url: https://typesense.org/support
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
  termsOfService: https://typesense.org/terms
servers:
- url: '{protocol}://{hostname}:{port}'
  description: Typesense Server
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    hostname:
      default: localhost
    port:
      default: '8108'
security:
- api_key_header: []
tags:
- name: Conversational Search
  description: Perform conversational search queries that return both traditional search results and AI-generated natural language answers.
paths:
  /collections/{collectionName}/documents/search:
    parameters:
    - $ref: '#/components/parameters/collectionName'
    get:
      operationId: conversationalSearch
      summary: Perform A Conversational Search
      description: Performs a search query with conversational RAG enabled. Typesense retrieves relevant documents and passes them as context to the configured LLM, which generates a natural language answer. Supports multi-turn conversations by passing a conversation_id to maintain context across queries.
      tags:
      - Conversational Search
      parameters:
      - name: q
        in: query
        required: true
        description: Natural language question or search query.
        schema:
          type: string
      - name: query_by
        in: query
        required: true
        description: Comma-separated list of fields to search against.
        schema:
          type: string
      - name: conversation
        in: query
        required: true
        description: Set to true to enable conversational search with RAG.
        schema:
          type: boolean
      - name: conversation_model_id
        in: query
        required: true
        description: ID of the conversation model to use for generating answers.
        schema:
          type: string
      - name: conversation_id
        in: query
        description: ID of an existing conversation to continue a multi-turn dialog. If not provided, a new conversation is started.
        schema:
          type: string
      - name: filter_by
        in: query
        description: Filter conditions to narrow the search scope.
        schema:
          type: string
      - name: sort_by
        in: query
        description: Sort conditions for the underlying search.
        schema:
          type: string
      - name: per_page
        in: query
        description: Number of documents to pass as context to the LLM.
        schema:
          type: integer
      responses:
        '200':
          description: Conversational search results with generated answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationalSearchResult'
        '400':
          description: Bad request - invalid conversation parameters
        '401':
          description: Unauthorized
        '404':
          description: Collection or conversation model not found
components:
  schemas:
    ConversationalSearchResult:
      type: object
      properties:
        facet_counts:
          type: array
          description: Facet counts from the underlying search.
          items:
            type: object
        found:
          type: integer
          description: Total number of matching documents.
        search_time_ms:
          type: integer
          description: Time taken for the search in milliseconds.
        hits:
          type: array
          description: Search result hits used as context for the answer.
          items:
            type: object
            properties:
              document:
                type: object
                description: The matched document.
              highlights:
                type: array
                items:
                  type: object
              text_match:
                type: integer
                format: int64
        conversation:
          type: object
          description: Conversational response from the LLM.
          required:
          - answer
          - conversation_id
          properties:
            answer:
              type: string
              description: Natural language answer generated by the LLM based on the search results context.
            conversation_history:
              type: array
              description: History of messages in the conversation.
              items:
                type: object
                properties:
                  role:
                    type: string
                    description: Role of the message sender (user, assistant, system).
                  content:
                    type: string
                    description: Content of the message.
            conversation_id:
              type: string
              description: Unique ID for the conversation, used for follow-up queries.
  parameters:
    collectionName:
      name: collectionName
      in: path
      required: true
      description: Name of the collection to search.
      schema:
        type: string
  securitySchemes:
    api_key_header:
      type: apiKey
      in: header
      name: X-TYPESENSE-API-KEY
      description: API key for authenticating requests to the Typesense server.
externalDocs:
  description: Typesense Analytics Documentation
  url: https://typesense.org/docs/30.1/api/analytics-query-suggestions.html