The Typesense Vector Search API extends the core search capabilities with vector and hybrid search. It supports indexing embedding fields, querying by vector proximity, and combining semantic vector search with keyword search for superior relevance.
openapi: 3.1.0
info:
title: Typesense Analytics Analytics Events Vector 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: Vector Search
description: Perform nearest-neighbor vector search, hybrid keyword-vector search, and semantic search queries.
paths:
/collections/{collectionName}/documents/search:
parameters:
- $ref: '#/components/parameters/collectionName'
get:
operationId: vectorSearch
summary: Perform Vector Or Hybrid Search
description: Searches for documents using vector similarity, keyword matching, or a hybrid combination of both. When vector_query is specified, Typesense performs nearest-neighbor search using the specified vector field. When combined with a text query (q parameter), results are scored using a hybrid approach that blends keyword relevance and vector similarity.
tags:
- Vector Search
parameters:
- name: q
in: query
description: Text search query. Use * for pure vector search without keyword matching.
schema:
type: string
- name: query_by
in: query
required: true
description: Comma-separated list of fields to search against for keyword matching.
schema:
type: string
- name: vector_query
in: query
description: Vector query in the format field_name:([v1,v2,...],k:num) or field_name:([], id:doc_id) for finding similar documents. The k parameter controls how many nearest neighbors to return.
schema:
type: string
- name: filter_by
in: query
description: Filter conditions to narrow search results.
schema:
type: string
- name: sort_by
in: query
description: Sort conditions. Use _vector_distance for sorting by vector similarity.
schema:
type: string
- 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: 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: prefix
in: query
description: Whether prefix search is enabled for keyword matching.
schema:
type: string
responses:
'200':
description: Vector search results returned
content:
application/json:
schema:
$ref: '#/components/schemas/VectorSearchResult'
'400':
description: Bad request - invalid vector query
'401':
description: Unauthorized
'404':
description: Collection not found
/multi_search:
post:
operationId: multiVectorSearch
summary: Multi-search With Vector Queries
description: Sends multiple search requests in a single HTTP request, where one or more requests can include vector queries for semantic or hybrid search across different collections.
tags:
- Vector Search
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- searches
properties:
searches:
type: array
description: Array of search requests, each optionally including a vector_query parameter.
items:
$ref: '#/components/schemas/VectorMultiSearchParameters'
responses:
'200':
description: Multi-search results
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/VectorSearchResult'
'400':
description: Bad request
'401':
description: Unauthorized
components:
schemas:
VectorSearchResult:
type: object
properties:
facet_counts:
type: array
description: Facet value counts for the search results.
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.
out_of:
type: integer
description: Total number of documents in the collection.
page:
type: integer
description: Current page number.
hits:
type: array
description: Array of search result hits with vector distance scores.
items:
$ref: '#/components/schemas/VectorSearchHit'
VectorSearchHit:
type: object
properties:
document:
type: object
description: The matched document.
highlights:
type: array
description: Highlighted field snippets for keyword matches.
items:
type: object
text_match:
type: integer
format: int64
description: Keyword text match score.
vector_distance:
type: number
format: float
description: Distance between the query vector and the document vector. Lower values indicate greater similarity for cosine distance.
hybrid_search_info:
type: object
description: Information about hybrid scoring when both keyword and vector search are combined.
properties:
text_match_score:
type: number
description: Normalized text match score component.
vector_distance_score:
type: number
description: Normalized vector distance score component.
rank_fusion_score:
type: number
description: Combined score from rank fusion of text and vector scores.
VectorMultiSearchParameters:
type: object
required:
- collection
properties:
collection:
type: string
description: Name of the collection to search.
q:
type: string
description: Text search query. Use * for pure vector search.
query_by:
type: string
description: Fields to search for keyword matching.
vector_query:
type: string
description: Vector query for nearest-neighbor search.
filter_by:
type: string
description: Filter conditions.
sort_by:
type: string
description: Sort conditions.
page:
type: integer
description: Page number.
per_page:
type: integer
description: Results per page.
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