Typesense Multi-Search API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events Multi-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: Multi-Search
  description: Send multiple search requests across one or more collections in a single HTTP request.
paths:
  /multi_search:
    post:
      operationId: multiSearch
      summary: Multi-search Across Collections
      description: Sends multiple search requests in a single HTTP request. Each search can target a different collection with different parameters. Useful for federated search and reducing network round trips.
      tags:
      - Multi-Search
      parameters:
      - name: limit_multi_searches
        in: query
        description: Maximum number of search requests allowed in a single multi-search.
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - searches
              properties:
                searches:
                  type: array
                  description: Array of search request objects.
                  items:
                    $ref: '#/components/schemas/MultiSearchParameters'
      responses:
        '200':
          description: Multi-search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSearchResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
components:
  schemas:
    SearchResult:
      type: object
      properties:
        facet_counts:
          type: array
          description: Facet value counts for the search results.
          items:
            $ref: '#/components/schemas/FacetCounts'
        found:
          type: integer
          description: Total number of documents matching the query.
        found_docs:
          type: integer
          description: Total number of documents found before grouping.
        search_time_ms:
          type: integer
          description: Time taken for the search in milliseconds.
        out_of:
          type: integer
          description: Total number of documents in the collection.
        search_cutoff:
          type: boolean
          description: Whether the search was cut off due to time limits.
        page:
          type: integer
          description: Current page number.
        hits:
          type: array
          description: Array of search result hits.
          items:
            $ref: '#/components/schemas/SearchResultHit'
        grouped_hits:
          type: array
          description: Array of grouped search result hits when group_by is used.
          items:
            $ref: '#/components/schemas/SearchGroupedHit'
        request_params:
          type: object
          description: Parameters used for the search request.
        conversation:
          type: object
          description: Conversational search response when conversation mode is enabled.
          properties:
            answer:
              type: string
              description: Generated answer from the conversation model.
            conversation_history:
              type: array
              description: History of the conversation.
              items:
                type: object
            conversation_id:
              type: string
              description: ID of the conversation for follow-up queries.
    SearchGroupedHit:
      type: object
      properties:
        found:
          type: integer
          description: Number of hits in this group.
        group_key:
          type: array
          description: Values of the group_by field.
          items: {}
        hits:
          type: array
          description: Search hits within this group.
          items:
            $ref: '#/components/schemas/SearchResultHit'
    FacetCounts:
      type: object
      properties:
        field_name:
          type: string
          description: Name of the faceted field.
        counts:
          type: array
          description: Array of facet value counts.
          items:
            type: object
            properties:
              count:
                type: integer
                description: Number of documents with this facet value.
              highlighted:
                type: string
                description: Highlighted facet value.
              value:
                type: string
                description: Facet value.
        stats:
          type: object
          description: Statistics for numeric faceted fields.
          properties:
            min:
              type: number
            max:
              type: number
            sum:
              type: number
            avg:
              type: number
            total_values:
              type: integer
    SearchHighlight:
      type: object
      properties:
        field:
          type: string
          description: Name of the highlighted field.
        snippet:
          type: string
          description: Highlighted snippet of the field value.
        snippets:
          type: array
          description: Array of highlighted snippets for array fields.
          items:
            type: string
        value:
          type: string
          description: Full highlighted field value.
        values:
          type: array
          description: Full highlighted values for array fields.
          items:
            type: string
        matched_tokens:
          type: array
          description: Tokens in the field that matched the query.
          items: {}
        indices:
          type: array
          description: Indices of matched values in array fields.
          items:
            type: integer
    MultiSearchResult:
      type: object
      properties:
        results:
          type: array
          description: Array of search results, one per search request.
          items:
            $ref: '#/components/schemas/SearchResult'
        conversation:
          type: object
          description: Conversation context when conversational multi-search is used.
    MultiSearchParameters:
      type: object
      required:
      - collection
      properties:
        collection:
          type: string
          description: Name of the collection to search.
        q:
          type: string
          description: Search query string.
        query_by:
          type: string
          description: Comma-separated list of fields to search.
        filter_by:
          type: string
          description: Filter conditions.
        sort_by:
          type: string
          description: Sort conditions.
        facet_by:
          type: string
          description: Fields to facet on.
        page:
          type: integer
          description: Page number.
        per_page:
          type: integer
          description: Results per page.
        preset:
          type: string
          description: Name of a preset to apply.
    SearchResultHit:
      type: object
      properties:
        document:
          type: object
          description: The matched document.
        highlights:
          type: array
          description: Array of field highlights with matched tokens.
          items:
            $ref: '#/components/schemas/SearchHighlight'
        highlight:
          type: object
          description: Structured highlight object with nested field support.
        text_match:
          type: integer
          format: int64
          description: Text match score for the hit.
        text_match_info:
          type: object
          description: Detailed text match scoring breakdown.
        geo_distance_meters:
          type: object
          description: Distance in meters from the search geo point.
        vector_distance:
          type: number
          format: float
          description: Distance from the query vector for vector searches.
        hybrid_search_info:
          type: object
          description: Information about hybrid keyword and vector search scoring.
  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