Typesense Vector Search API

openapi: 3.1.0
info:
  title: Typesense Vector Search API
  description: >-
    The Typesense Vector Search API enables nearest-neighbor search over
    embeddings generated by machine learning models. It supports semantic
    search, visual search, and recommendation use cases by indexing vector
    embeddings alongside structured data. Typesense can automatically generate
    embeddings using built-in models or integrate with external services like
    OpenAI, allowing developers to build hybrid search experiences that combine
    keyword and semantic search in a single query.
  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
externalDocs:
  description: Typesense Semantic Search Guide
  url: https://typesense.org/docs/guide/semantic-search.html
servers:
  - url: '{protocol}://{hostname}:{port}'
    description: Typesense Server
    variables:
      protocol:
        default: http
        enum:
          - http
          - https
      hostname:
        default: localhost
      port:
        default: '8108'
tags:
  - name: NL Search Models
    description: >-
      Manage natural language search models used for query understanding and
      semantic matching.
  - name: Vector Collections
    description: >-
      Create and manage collections with vector fields for semantic search and
      nearest-neighbor queries.
  - name: Vector Search
    description: >-
      Perform nearest-neighbor vector search, hybrid keyword-vector search,
      and semantic search queries.
security:
  - api_key_header: []
paths:
  /collections:
    post:
      operationId: createVectorCollection
      summary: Create A Collection With Vector Fields
      description: >-
        Creates a collection that includes vector embedding fields for semantic
        search. Vector fields are defined with a type of float[] and a num_dim
        property specifying the number of dimensions. The embed property can be
        used to configure automatic embedding generation from source fields
        using built-in models or external APIs like OpenAI.
      tags:
        - Vector Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VectorCollectionSchema'
      responses:
        '201':
          description: Vector collection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VectorCollectionResponse'
        '400':
          description: Bad request - invalid schema or embedding configuration
        '401':
          description: Unauthorized
        '409':
          description: Conflict - collection already exists
  /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
  /nl_search_models:
    get:
      operationId: listNLSearchModels
      summary: List All NL Search Models
      description: >-
        Retrieves all natural language search models configured in the
        Typesense instance. NL search models are used for query understanding
        and semantic matching.
      tags:
        - NL Search Models
      responses:
        '200':
          description: List of NL search models
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NLSearchModel'
        '401':
          description: Unauthorized
    post:
      operationId: createNLSearchModel
      summary: Create An NL Search Model
      description: >-
        Creates a new natural language search model configuration for semantic
        query understanding.
      tags:
        - NL Search Models
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLSearchModelCreateSchema'
      responses:
        '201':
          description: NL search model created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModel'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /nl_search_models/{modelId}:
    parameters:
      - $ref: '#/components/parameters/modelId'
    get:
      operationId: getNLSearchModel
      summary: Retrieve An NL Search Model
      description: >-
        Retrieves a specific NL search model by ID.
      tags:
        - NL Search Models
      responses:
        '200':
          description: NL search model retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModel'
        '401':
          description: Unauthorized
        '404':
          description: Model not found
    put:
      operationId: updateNLSearchModel
      summary: Update An NL Search Model
      description: >-
        Updates an existing NL search model configuration.
      tags:
        - NL Search Models
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLSearchModelUpdateSchema'
      responses:
        '200':
          description: NL search model updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModel'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Model not found
    delete:
      operationId: deleteNLSearchModel
      summary: Delete An NL Search Model
      description: >-
        Deletes an NL search model by ID.
      tags:
        - NL Search Models
      responses:
        '200':
          description: NL search model deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      ID of the deleted model.
        '401':
          description: Unauthorized
        '404':
          description: Model not found
components:
  securitySchemes:
    api_key_header:
      type: apiKey
      in: header
      name: X-TYPESENSE-API-KEY
      description: >-
        API key for authenticating requests to the Typesense server.
  parameters:
    collectionName:
      name: collectionName
      in: path
      required: true
      description: >-
        Name of the collection.
      schema:
        type: string
    modelId:
      name: modelId
      in: path
      required: true
      description: >-
        ID of the NL search model.
      schema:
        type: string
  schemas:
    VectorCollectionSchema:
      type: object
      required:
        - name
        - fields
      properties:
        name:
          type: string
          description: >-
            Name of the collection.
        fields:
          type: array
          description: >-
            Field definitions including vector embedding fields.
          items:
            $ref: '#/components/schemas/VectorField'
        default_sorting_field:
          type: string
          description: >-
            Default field for sorting results.
        enable_nested_fields:
          type: boolean
          description: >-
            Whether to enable indexing of nested object fields.
    VectorCollectionResponse:
      type: object
      properties:
        name:
          type: string
          description: >-
            Name of the collection.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/VectorField'
        num_documents:
          type: integer
          format: int64
          description: >-
            Number of documents in the collection.
        created_at:
          type: integer
          format: int64
          description: >-
            Unix timestamp when the collection was created.
    VectorField:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: >-
            Name of the field.
        type:
          type: string
          description: >-
            Data type. Use float[] for vector embedding fields.
        optional:
          type: boolean
          description: >-
            Whether this field is optional.
        facet:
          type: boolean
          description: >-
            Whether this field can be used for faceting.
        index:
          type: boolean
          description: >-
            Whether this field should be indexed.
        num_dim:
          type: integer
          description: >-
            Number of dimensions for vector fields. Required for float[] type
            fields used as embeddings.
        vec_dist:
          type: string
          description: >-
            Distance metric for nearest-neighbor search.
          enum:
            - cosine
            - ip
        embed:
          $ref: '#/components/schemas/EmbedConfig'
    EmbedConfig:
      type: object
      description: >-
        Configuration for automatic embedding generation from source fields.
      properties:
        from:
          type: array
          description: >-
            Field names to generate embeddings from. Typesense concatenates
            these fields and generates an embedding vector.
          items:
            type: string
        model_config:
          type: object
          description: >-
            Model configuration for embedding generation.
          properties:
            model_name:
              type: string
              description: >-
                Name of the embedding model. Supports built-in models like
                ts/all-MiniLM-L12-v2 or external models via OpenAI, Google,
                and other providers.
            api_key:
              type: string
              description: >-
                API key for external embedding services such as OpenAI.
            url:
              type: string
              description: >-
                URL of an external embedding service endpoint.
            access_token:
              type: string
              description: >-
                Access token for embedding service authentication.
            client_id:
              type: string
              description: >-
                Client ID for OAuth-based embedding services.
            client_secret:
              type: string
              description: >-
                Client secret for OAuth-based embedding services.
            project_id:
              type: string
              description: >-
                Project ID for cloud-based embedding services.
    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.
    NLSearchModelCreateSchema:
      type: object
      required:
        - model_name
      properties:
        model_name:
          type: string
          description: >-
            Name of the natural language search model.
        api_key:
          type: string
          description: >-
            API key for accessing the model provider.
        model_config:
          type: object
          description: >-
            Additional model configuration parameters.
    NLSearchModelUpdateSchema:
      type: object
      properties:
        model_name:
          type: string
          description: >-
            Updated model name.
        api_key:
          type: string
          description: >-
            Updated API key.
        model_config:
          type: object
          description: >-
            Updated model configuration.
    NLSearchModel:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier of the NL search model.
        model_name:
          type: string
          description: >-
            Name of the model.
        model_config:
          type: object
          description: >-
            Model configuration parameters.