Typesense Search API

openapi: 3.1.0
info:
  title: Typesense Search API
  description: >-
    The Typesense Search API provides endpoints for creating and managing
    collections, indexing documents, and performing search queries. It supports
    typo-tolerant full-text search, faceted navigation, filtering, sorting,
    geo-based search, and federated multi-search across collections. The API
    also covers synonym sets, curation sets, collection aliases, stopwords,
    presets, stemming dictionaries, API key management, and cluster operations.
  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 API Documentation
  url: https://typesense.org/docs/30.1/api/
servers:
  - url: '{protocol}://{hostname}:{port}'
    description: Typesense Server
    variables:
      protocol:
        default: http
        enum:
          - http
          - https
      hostname:
        default: localhost
      port:
        default: '8108'
tags:
  - name: API Keys
    description: >-
      Create and manage API keys with fine-grained access control on a
      per-collection, per-action, or per-record level.
  - name: Collection Aliases
    description: >-
      Create and manage aliases that point to collections, enabling zero-downtime
      reindexing.
  - name: Collections
    description: >-
      Create, retrieve, update, and delete collections. A collection is a group
      of related documents with a defined schema.
  - name: Configuration
    description: >-
      Server configuration management including slow request logging.
  - name: Curation Sets
    description: >-
      Manage top-level curation sets for pinning, hiding, and boosting search
      results across collections.
  - name: Documents
    description: >-
      Index, retrieve, update, delete, import, and export documents within a
      collection.
  - name: Monitoring
    description: >-
      Health checks, debug information, metrics, and API statistics.
  - name: Multi-Search
    description: >-
      Send multiple search requests across one or more collections in a single
      HTTP request.
  - name: Operations
    description: >-
      Cluster operations including snapshots, cache management, compaction, and
      voting.
  - name: Presets
    description: >-
      Store and reference named sets of search parameters for reuse across
      queries.
  - name: Search
    description: >-
      Search for documents in a collection with typo tolerance, faceting,
      filtering, sorting, geo search, and grouping.
  - name: Stemming
    description: >-
      Manage stemming dictionaries for custom word stemming rules.
  - name: Stopwords
    description: >-
      Manage stopword sets that define keywords to be removed from search
      queries.
  - name: Synonym Sets
    description: >-
      Manage top-level synonym sets that can be shared across multiple
      collections.
security:
  - api_key_header: []
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
  /collections/{collectionName}/documents:
    parameters:
      - $ref: '#/components/parameters/collectionName'
    post:
      operationId: indexDocument
      summary: Index A Document
      description: >-
        Indexes a single document into the specified collection. If the document
        contains an id field of type string, Typesense will use that as the
        identifier. Otherwise, an auto-generated identifier is assigned.
      tags:
        - Documents
      parameters:
        - name: action
          in: query
          description: >-
            Additional action to perform. Use create, upsert, update, or
            emplace.
          schema:
            $ref: '#/components/schemas/IndexAction'
        - name: dirty_values
          in: query
          description: >-
            How to handle field values that do not match the schema type.
          schema:
            $ref: '#/components/schemas/DirtyValues'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                A JSON document matching the collection schema.
      responses:
        '201':
          description: Document indexed successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request - document does not match schema
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
    patch:
      operationId: updateDocuments
      summary: Update Documents With Conditional Query
      description: >-
        Updates multiple documents that match a given filter condition. Only the
        fields specified in the request body are updated.
      tags:
        - Documents
      parameters:
        - name: filter_by
          in: query
          required: true
          description: >-
            A filter expression to identify documents to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Partial document with fields to update.
      responses:
        '200':
          description: Documents updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  num_updated:
                    type: integer
                    description: >-
                      Number of documents updated.
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
    delete:
      operationId: deleteDocuments
      summary: Delete Documents By Query
      description: >-
        Deletes documents that match a given filter condition from the
        collection.
      tags:
        - Documents
      parameters:
        - name: filter_by
          in: query
          required: true
          description: >-
            A filter expression to identify documents to delete.
          schema:
            type: string
        - name: batch_size
          in: query
          description: >-
            Number of documents to delete per batch.
          schema:
            type: integer
      responses:
        '200':
          description: Documents deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  num_deleted:
                    type: integer
                    description: >-
                      Number of documents deleted.
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
  /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
  /collections/{collectionName}/documents/export:
    parameters:
      - $ref: '#/components/parameters/collectionName'
    get:
      operationId: exportDocuments
      summary: Export Documents From A Collection
      description: >-
        Exports all documents from a collection as a stream of JSONL-formatted
        lines. Supports filtering to export a subset of documents.
      tags:
        - Documents
      parameters:
        - name: filter_by
          in: query
          description: >-
            Filter condition to export a subset of documents.
          schema:
            type: string
        - name: include_fields
          in: query
          description: >-
            Comma-separated list of fields to include.
          schema:
            type: string
        - name: exclude_fields
          in: query
          description: >-
            Comma-separated list of fields to exclude.
          schema:
            type: string
      responses:
        '200':
          description: Documents exported as JSONL stream
          content:
            application/octet-stream:
              schema:
                type: string
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
  /collections/{collectionName}/documents/import:
    parameters:
      - $ref: '#/components/parameters/collectionName'
    post:
      operationId: importDocuments
      summary: Import Documents Into A Collection
      description: >-
        Imports multiple documents into a collection via a JSONL-formatted
        request body. Supports create, upsert, update, and emplace actions.
      tags:
        - Documents
      parameters:
        - name: action
          in: query
          description: >-
            The import action to perform. Use create, upsert, update, or
            emplace.
          schema:
            $ref: '#/components/schemas/IndexAction'
        - name: batch_size
          in: query
          description: >-
            Number of documents to process per batch.
          schema:
            type: integer
        - name: dirty_values
          in: query
          description: >-
            How to handle values that do not match the schema type.
          schema:
            $ref: '#/components/schemas/DirtyValues'
        - name: return_id
          in: query
          description: >-
            Whether to return the document ID in the response.
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: >-
                JSONL-formatted documents, one JSON object per line.
      responses:
        '200':
          description: Import results as JSONL stream
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request - malformed import data
        '401':
          description: Unauthorized
        '404':
          description: Collection not found
  /collections/{collectionName}/documents/{documentId}:
    parameters:
      - $ref: '#/components/parameters/collectionName'
      - $ref: '#/components/parameters/documentId'
    get:
      operationId: getDocument
      summary: Retrieve A Document
      description: >-
        Retrieves a single document from a collection by its ID.
      tags:
        - Documents
      responses:
        '200':
          description: Document retrieved successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Document or collection not found
    patch:
      operationId: updateDocument
      summary: Update A Document
      description: >-
        Partially updates a document in the collection. Only the fields
        specified in the request body are updated.
      tags:
        - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Partial document with fields to update.
      responses:
        '200':
          description: Document updated successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Document or collection not found
    delete:
      operationId: deleteDocument
      summary: Delete A Document
      description: >-
        Deletes a single document from a collection by its ID.
      tags:
        - Documents
      responses:
        '200':
          description: Document deleted successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Document or collection not found
  /multi_search:
    post:
      operationId: multiSearch
      summary: Multi-search Across Collections
      description: >-
        Sends multiple search requests in a single HTTP request. Each search
        can target a different collection with different parameters. Useful for
        federated search and reducing network round trips.
      tags:
        - Multi-Search
      parameters:
        - name: limit_multi_searches
          in: query
          description: >-
            Maximum number of search requests allowed in a single multi-search.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - searches
              properties:
                searches:
                  type: array
                  description: >-
                    Array of search request objects.
                  items:
                    $ref: '#/components/schemas/MultiSearchParameters'
      responses:
        '200':
          description: Multi-search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSearchResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /synonym_sets:
    get:
      operationId: listSynonymSets
      summary: List All Synonym Sets
      description: >-
        Retrieves all synonym sets defined in the Typesense instance. Synonym
        sets are top-level resources that can be shared across collections.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: List of synonym sets
          content:
            application/json:
              schema:
                type: object
                properties:
                  synonym_sets:
                    type: array
                    items:
                      $ref: '#/components/schemas/SynonymSet'
        '401':
          description: Unauthorized
  /synonym_sets/{synonymSetName}:
    parameters:
      - $ref: '#/components/parameters/synonymSetName'
    get:
      operationId: getSynonymSet
      summary: Retrieve A Synonym Set
      description: >-
        Retrieves a specific synonym set by name.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: Synonym set retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymSet'
        '401':
          description: Unauthorized
        '404':
          description: Synonym set not found
    put:
      operationId: upsertSynonymSet
      summary: Create Or Update A Synonym Set
      description: >-
        Creates a new synonym set or updates an existing one by name.
      tags:
        - Synonym Sets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynonymSetSchema'
      responses:
        '200':
          description: Synonym set upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymSet'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteSynonymSet
      summary: Delete A Synonym Set
      description: >-
        Deletes a synonym set by name.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: Synonym set deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessStatus'
        '401':
          description: Unauthorized
        '404':
          description: Synonym set not found
  /synonym_sets/{synonymSetName}/items:
    parameters:
      - $ref: '#/components/parameters/synonymSetName'
    get:
      operationId: listSynonymSetItems
      summary: List Items In A Synonym Set
      description: >-
        Retrieves all synonym items within a specific synonym set.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: List of synonym items
          content:
            application/json:
              schema:
                type: object
                properties:
                  synonyms:
                    type: array
                    items:
                      $ref: '#/components/schemas/SynonymItem'
        '401':
          description: Unauthorized
        '404':
          description: Synonym set not found
  /synonym_sets/{synonymSetName}/items/{itemId}:
    parameters:
      - $ref: '#/components/parameters/synonymSetName'
      - $ref: '#/components/parameters/itemId'
    get:
      operationId: getSynonymSetItem
      summary: Retrieve A Synonym Set Item
      description: >-
        Retrieves a specific synonym item by ID from a synonym set.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: Synonym item retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymItem'
        '401':
          description: Unauthorized
        '404':
          description: Synonym item or set not found
    put:
      operationId: upsertSynonymSetItem
      summary: Create Or Update A Synonym Set Item
      description: >-
        Creates or updates a synonym item within a synonym set.
      tags:
        - Synonym Sets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynonymItemSchema'
      responses:
        '200':
          description: Synonym item upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymItem'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteSynonymSetItem
      summary: Delete A Synonym Set Item
      description: >-
        Deletes a specific synonym item from a synonym set.
      tags:
        - Synonym Sets
      responses:
        '200':
          description: Synonym item deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessStatus'
        '401':
          description: Unauthorized
        '404':
          description: Synonym item or set not found
  /curation_sets:
    get:
      operationId: listCurationSets
      summary: List All Curation Sets
      description: >-
        Retrieves all curation sets. Curation sets are top-level resources for
        pinning, hiding, and boosting search results across collections.
      tags:
        - Curation Sets
      responses:
        '200':
          description: List of curation sets
          content:
            application/json:
              schema:
                type: object
                properties:
                  curation_sets:
                    type: array
                    items:
                      $ref: '#/components/schemas/CurationSet'
        '401':
          description: Unauthorized
  /curation_sets/{curationSetName}:
    parameters:
      - $ref: '#/components/parameters/curationSetName'
    get:
      operationId: getCurationSet
      summary: Retrieve A Curation Set
      description: >-
        Retrieves a specific curation set by name.
      tags:
        - Curation Sets
      responses:
        '200':
          description: Curation set retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationSet'
        '401':
          description: Unauthorized
        '404':
          description: Curation set not found
    put:
      operationId: upsertCurationSet
      summary: Create Or Update A Curation Set
      description: >-
        Creates a new curation set or updates an existing one.
      tags:
        - Curation Sets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurationSetSchema'
      responses:
        '200':
          description: Curation set upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationSet'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteCurationSet
      summary: Delete A Curation Set
      description: >-
        Deletes a curation set by name.
      tags:
        - Curation Sets
      responses:
        '200':
          description: Curation set deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessStatus'
        '401':
          description: Unauthorized
        '404':
          description: Curation set not found
  /curation_sets/{curationSetName}/items:
    parameters:
      - $ref: '#/components/parameters/curationSetName'
    get:
      operationId: listCurationSetItems
      summary: List Items In A Curation Set
      description: >-
        Retrieves all curation items within a specific curation set.
      tags:
        - Curation Sets
      responses:
        '200':
          description: List of curation items
          content:
            application/json:
              schema:
                type: object
                properties:
                  curations:
                    type: array
                    items:
                      $ref: '#/components/schemas/CurationItem'
        '401':
          description: Unauthorized
        '404':
          description: Curation set not found
  /curation_sets/{curationSetName}/items/{itemId}:
    parameters:
      - $ref: '#/components/parameters/curationSetName'
      - $ref: '#/components/parameters/itemId'
    get:
      operationId: getCurationSetItem
      summary: Retrieve A Curation Set Item
      description: >-
        Retrieves a specific curation item by ID.
      tags:
        - Curation Sets
      responses:
        '200':
          description: Curation item retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationItem'
        '401':
          description: Unauthorized
        '404

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/typesense/refs/heads/main/openapi/typesense-search-api-openapi.yml