Typesense Collections API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events 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: Collections
  description: Create, retrieve, update, and delete collections. A collection is a group of related documents with a defined schema.
paths:
  /collections:
    get:
      operationId: listCollections
      summary: List All Collections
      description: Returns a summary of all collections, including the name, number of documents, and schema for each collection.
      tags:
      - Collections
      responses:
        '200':
          description: Successfully retrieved list of collections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CollectionResponse'
        '401':
          description: Unauthorized - invalid or missing API key
    post:
      operationId: createCollection
      summary: Create A New Collection
      description: Creates a new collection with the specified schema. A collection defines the fields that will be indexed from documents. Before adding documents to Typesense, you must first create a collection.
      tags:
      - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionSchema'
      responses:
        '201':
          description: Collection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '400':
          description: Bad request - invalid schema
        '401':
          description: Unauthorized - invalid or missing API key
        '409':
          description: Conflict - collection already exists
  /collections/{collectionName}:
    parameters:
    - $ref: '#/components/parameters/collectionName'
    get:
      operationId: getCollection
      summary: Retrieve A Collection
      description: Retrieves the schema and metadata of a specific collection by name.
      tags:
      - Collections
      responses:
        '200':
          description: Successfully retrieved collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
    patch:
      operationId: updateCollection
      summary: Update A Collection
      description: Updates the schema of an existing collection. You can add new fields, drop existing fields, or modify field attributes.
      tags:
      - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionUpdateSchema'
      responses:
        '200':
          description: Collection updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '400':
          description: Bad request - invalid update
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
    delete:
      operationId: deleteCollection
      summary: Delete A Collection
      description: Permanently deletes a collection and all documents within it. This action cannot be undone.
      tags:
      - Collections
      responses:
        '200':
          description: Collection deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
components:
  parameters:
    collectionName:
      name: collectionName
      in: path
      required: true
      description: Name of the collection.
      schema:
        type: string
  schemas:
    Field:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Name of the field.
        type:
          type: string
          description: Data type of the field. Supported types include string, int32, int64, float, bool, string[], int32[], int64[], float[], bool[], auto, object, object[], geopoint, geopoint[], image.
          enum:
          - string
          - int32
          - int64
          - float
          - bool
          - string[]
          - int32[]
          - int64[]
          - float[]
          - bool[]
          - auto
          - object
          - object[]
          - geopoint
          - geopoint[]
          - image
        optional:
          type: boolean
          description: Whether this field is optional in documents.
        facet:
          type: boolean
          description: Whether this field can be used for faceting.
        index:
          type: boolean
          description: Whether this field should be indexed for search.
        sort:
          type: boolean
          description: Whether this field can be used for sorting.
        infix:
          type: boolean
          description: Whether infix search is enabled for this field.
        locale:
          type: string
          description: Locale for language-specific tokenization.
        reference:
          type: string
          description: Reference to a field in another collection for JOINs.
        num_dim:
          type: integer
          description: Number of dimensions for vector fields.
        store:
          type: boolean
          description: Whether to store the field value for retrieval.
        range_index:
          type: boolean
          description: Whether to build a range index for this field.
        stem:
          type: boolean
          description: Whether stemming is enabled for this field.
        stem_dictionary:
          type: string
          description: Name of the custom stemming dictionary to use.
        drop:
          type: boolean
          description: Whether to drop this field during a schema update.
        vec_dist:
          type: string
          description: Distance metric for vector fields.
          enum:
          - cosine
          - ip
        embed:
          type: object
          description: Embedding configuration for auto-generating vector embeddings.
          properties:
            from:
              type: array
              description: Field names to generate embeddings from.
              items:
                type: string
            model_config:
              type: object
              description: Model configuration for embedding generation.
              properties:
                model_name:
                  type: string
                  description: Name of the embedding model.
                api_key:
                  type: string
                  description: API key for external embedding services.
                url:
                  type: string
                  description: URL of the embedding service.
    VoiceQueryModelConfig:
      type: object
      properties:
        model_name:
          type: string
          description: Name of the voice query model.
    CollectionSchema:
      type: object
      required:
      - name
      - fields
      properties:
        name:
          type: string
          description: Name of the collection.
        fields:
          type: array
          description: Array of field definitions for the collection schema.
          items:
            $ref: '#/components/schemas/Field'
        default_sorting_field:
          type: string
          description: Name of the field to sort by when no sort_by parameter is specified.
        token_separators:
          type: array
          description: Characters to use as token separators in addition to whitespace.
          items:
            type: string
        symbols_to_index:
          type: array
          description: Characters that should be indexed as part of tokens.
          items:
            type: string
        enable_nested_fields:
          type: boolean
          description: Whether to enable indexing of nested object fields.
        synonym_sets:
          type: array
          description: List of synonym set names to attach to this collection.
          items:
            type: string
        voice_query_model:
          $ref: '#/components/schemas/VoiceQueryModelConfig'
        metadata:
          type: object
          description: Arbitrary metadata to store with the collection.
    CollectionResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the collection.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        default_sorting_field:
          type: string
          description: Default sorting field for this collection.
        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.
        token_separators:
          type: array
          items:
            type: string
        symbols_to_index:
          type: array
          items:
            type: string
        enable_nested_fields:
          type: boolean
          description: Whether nested field indexing is enabled.
    CollectionUpdateSchema:
      type: object
      properties:
        fields:
          type: array
          description: Array of field definitions to add, modify, or drop.
          items:
            $ref: '#/components/schemas/Field'
        synonym_sets:
          type: array
          description: Updated list of synonym set names for this collection.
          items:
            type: string
        metadata:
          type: object
          description: Updated metadata for the collection.
  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