Typesense Search API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events 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: Search
  description: Search for documents in a collection with typo tolerance, faceting, filtering, sorting, geo search, and grouping.
paths:
  /collections/{collectionName}/documents/search:
    parameters:
    - $ref: '#/components/parameters/collectionName'
    get:
      operationId: searchCollection
      summary: Search For Documents
      description: Searches for documents in a collection using full-text search with typo tolerance, faceting, filtering, sorting, grouping, geo search, and vector search capabilities.
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: true
        description: The search query string. Use * for wildcard queries.
        schema:
          type: string
      - name: query_by
        in: query
        required: true
        description: Comma-separated list of fields to search against.
        schema:
          type: string
      - name: query_by_weights
        in: query
        description: Comma-separated weights for each query_by field.
        schema:
          type: string
      - name: text_match_type
        in: query
        description: How text matching is calculated. Options are max_score or max_weight.
        schema:
          type: string
      - name: prefix
        in: query
        description: Whether prefix search is enabled for query_by fields.
        schema:
          type: string
      - name: infix
        in: query
        description: Enable infix search for specified fields.
        schema:
          type: string
      - name: filter_by
        in: query
        description: Filter conditions for narrowing search results.
        schema:
          type: string
      - name: sort_by
        in: query
        description: Comma-separated list of fields and sort directions.
        schema:
          type: string
      - name: facet_by
        in: query
        description: Comma-separated list of fields to facet on.
        schema:
          type: string
      - name: max_facet_values
        in: query
        description: Maximum number of facet values to return.
        schema:
          type: integer
      - name: facet_query
        in: query
        description: Facet query for filtering facet values.
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination.
        schema:
          type: integer
          minimum: 1
      - name: per_page
        in: query
        description: Number of results per page.
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - name: group_by
        in: query
        description: Field to group results by.
        schema:
          type: string
      - name: group_limit
        in: query
        description: Maximum number of hits per group.
        schema:
          type: integer
      - name: include_fields
        in: query
        description: Comma-separated list of fields to include in results.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Comma-separated list of fields to exclude from results.
        schema:
          type: string
      - name: highlight_fields
        in: query
        description: Comma-separated list of fields to highlight.
        schema:
          type: string
      - name: highlight_full_fields
        in: query
        description: Fields for which full highlights are returned.
        schema:
          type: string
      - name: num_typos
        in: query
        description: Number of typographical errors to tolerate per token.
        schema:
          type: string
      - name: typo_tokens_threshold
        in: query
        description: Minimum token count to enable typo tolerance.
        schema:
          type: integer
      - name: drop_tokens_threshold
        in: query
        description: Token threshold below which tokens are dropped from query.
        schema:
          type: integer
      - name: pinned_hits
        in: query
        description: Comma-separated list of document IDs to pin at specific positions.
        schema:
          type: string
      - name: hidden_hits
        in: query
        description: Comma-separated list of document IDs to hide from results.
        schema:
          type: string
      - name: enable_overrides
        in: query
        description: Whether to apply curations and overrides.
        schema:
          type: boolean
      - name: preset
        in: query
        description: Name of a preset to use for search parameters.
        schema:
          type: string
      - name: vector_query
        in: query
        description: Vector query for nearest-neighbor search.
        schema:
          type: string
      - name: conversation
        in: query
        description: Whether to enable conversational search (RAG).
        schema:
          type: boolean
      - name: conversation_model_id
        in: query
        description: ID of the conversation model to use.
        schema:
          type: string
      - name: conversation_id
        in: query
        description: ID of an existing conversation to continue.
        schema:
          type: string
      responses:
        '200':
          description: Search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Bad request - invalid search parameters
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
components:
  schemas:
    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'
    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.
    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
    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.
  parameters:
    collectionName:
      name: collectionName
      in: path
      required: true
      description: Name of the collection.
      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