Typesense Vector Collections API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events Vector Collections 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 Collections
  description: Create and manage collections with vector fields for semantic search and nearest-neighbor queries.
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
components:
  schemas:
    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.
    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'
  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