openapi.yml

openapi: 3.0.3
info:
  title: Typesense API
  description: "An open source search engine for building delightful search experiences."
  version: '28.0'
externalDocs:
  description: Find out more about Typsesense
  url: https://typesense.org
security:
  - api_key_header: []
tags:
  - name: collections
    description: A collection is defined by a schema
    externalDocs:
      description: Find out more
      url: https://typesense.org/api/#create-collection
  - name: documents
    description: A document is an individual record to be indexed and belongs to a collection
    externalDocs:
      description: Find out more
      url: https://typesense.org/api/#index-document
  - name: curation
    description: Hand-curate search results based on conditional business rules
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/0.23.0/api/#curation
  - name: analytics
    description: Typesense can aggregate search queries for both analytics purposes and for query suggestions.
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/analytics-query-suggestions.html
  - name: keys
    description: Manage API Keys with fine-grain access control
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/0.23.0/api/#api-keys
  - name: debug
    description: Debugging information
  - name: operations
    description: Manage Typesense cluster
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/cluster-operations.html
  - name: stopwords
    description: Manage stopwords sets
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/stopwords.html
  - name: presets
    description: Store and reference search parameters
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/search.html#presets
  - name: conversations
    description: Conversational Search (RAG)
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/conversational-search-rag.html
  - name: synonyms
    description: Manage synonyms
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/synonyms.html
  - name: stemming
    description: Manage stemming dictionaries
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/stemming.html
paths:
  /collections:
    get:
      tags:
        - collections
      summary: List all collections
      description:
        Returns a summary of all your collections. The collections are
        returned sorted by creation date, with the most recent collections appearing
        first.
      operationId: getCollections
      responses:
        '200':
          description: List of all collections
          content:
            application/json:
              schema:
                type: array
                x-go-type: "[]*CollectionResponse"
                items:
                  $ref: "#/components/schemas/CollectionResponse"
    post:
      tags:
        - collections
      summary: Create a new collection
      description:
        When a collection is created, we give it a name and describe the
        fields that will be indexed from the documents added to the collection.
      operationId: createCollection
      requestBody:
        description: The collection object to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionSchema"
        required: true
      responses:
        '201':
          description: Collection successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '409':
          description: Collection already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}:
    get:
      tags:
        - collections
      summary: Retrieve a single collection
      description: Retrieve the details of a collection, given its name.
      operationId: getCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    patch:
      tags:
        - collections
      summary: Update a collection
      description:
        Update a collection's schema to modify the fields and their types.
      operationId: updateCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to update
          required: true
          schema:
            type: string
      requestBody:
        description: The document object with fields to be updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionUpdateSchema"
        required: true
      responses:
        '200':
          description: The updated partial collection schema
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionUpdateSchema"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '404':
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - collections
      summary: Delete a collection
      description:
        Permanently drops a collection. This action cannot be undone. For
        large collections, this might have an impact on read latencies.
      operationId: deleteCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents:
    post:
      tags:
        - documents
      summary: Index a document
      description:
        A document to be indexed in a given collection must conform to
        the schema of the collection.
      operationId: indexDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to add the document to
          required: true
          schema:
            type: string
        - name: action
          in: query
          description: Additional action to perform
          schema:
            type: string
            example: upsert
            $ref: "#/components/schemas/IndexAction"
        - name: dirty_values
          in: query
          description: Dealing with Dirty Data
          schema:
            $ref: "#/components/schemas/DirtyValues"
      requestBody:
        description: The document object to be indexed
        content:
          application/json:
            schema:
              type: object
              description: Can be any key-value pair
              x-go-type: "interface{}"
        required: true
      responses:
        '201':
          description: Document successfully created/indexed
          content:
            application/json:
              schema:
                type: object
                description: Can be any key-value pair
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    patch:
      tags:
        - documents
      summary: Update documents with conditional query
      description:
        The filter_by query parameter is used to filter to specify a condition against which the documents are matched.
        The request body contains the fields that should be updated for any documents that match the filter condition.
        This endpoint is only available if the Typesense server is version `0.25.0.rc12` or later.
      operationId: updateDocuments
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to update documents in
          required: true
          schema:
            type: string
        - name: updateDocumentsParameters
          in: query
          schema:
            type: object
            properties:
              filter_by:
                type: string
                example: "num_employees:>100 && country: [USA, UK]"
      responses:
        '200':
          description:
            The response contains a single field, `num_updated`, indicating the number of documents affected.
          content:
            application/json:
              schema:
                type: object
                required:
                  - num_updated
                properties:
                  num_updated:
                    type: integer
                    description: The number of documents that have been updated
                    example: 1
        '400':
          description: 'Bad request, see error message for details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      requestBody:
        description: The document fields to be updated
        content:
          application/json:
            schema:
              type: object
              description: Can be any key-value pair
              x-go-type: "interface{}"
        required: true
    delete:
      tags:
        - documents
      summary: Delete a bunch of documents
      description:
        Delete a bunch of documents that match a specific filter condition.
        Use the `batch_size` parameter to control the number of documents that
        should deleted at a time. A larger value will speed up deletions, but will
        impact performance of other operations running on the server.
      operationId: deleteDocuments
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to delete documents from
          required: true
          schema:
            type: string
        - name: deleteDocumentsParameters
          in: query
          schema:
            type: object
            required:
              - filter_by
            properties:
              filter_by:
                type: string
                example: "num_employees:>100 && country: [USA, UK]"
              batch_size:
                description:
                  Batch size parameter controls the number of documents that should be deleted
                  at a time. A larger value will speed up deletions, but will impact performance
                  of other operations running on the server.
                type: integer
              ignore_not_found:
                type: boolean
              truncate:
                description: When true, removes all documents from the collection while preserving the collection and its schema.
                type: boolean
      responses:
        '200':
          description: Documents successfully deleted
          content:
            application/json:
              schema:
                type: object
                required:
                  - num_deleted
                properties:
                  num_deleted:
                    type: integer
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents/search:
    get:
      tags:
        - documents
      summary: Search for documents in a collection
      description: Search for documents in a collection that match the search criteria.
      operationId: searchCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: searchParameters
          required: true
          in: query
          schema:
            $ref: "#/components/schemas/SearchParameters"
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '404':
          description: The collection or field was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/overrides:
    get:
      tags:
        - documents
        - curation
      summary: List all collection overrides
      operationId: getSearchOverrides
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of all search overrides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverridesResponse"
  /collections/{collectionName}/overrides/{overrideId}:
    get:
      tags:
        - documents
        - override
      summary: Retrieve a single search override
      description: Retrieve the details of a search override, given its id.
      operationId: getSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The id of the search override
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Search override fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverride"
    put:
      tags:
        - documents
        - curation
      summary: Create or update an override to promote certain documents over others
      description:
        Create or update an override to promote certain documents over others.
        Using overrides, you can include or exclude specific documents for a given query.
      operationId: upsertSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The ID of the search override to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The search override object to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchOverrideSchema"
        required: true
      responses:
        '200':
          description: Created/updated search override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverride"
        '404':
          description: Search override not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - documents
        - curation
      summary: Delete an override associated with a collection
      operationId: deleteSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The ID of the search override to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The ID of the deleted search override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverrideDeleteResponse"
        '404':
          description: Search override not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/synonyms:
    get:
      tags:
        - synonyms
      summary: List all collection synonyms
      operationId: getSearchSynonyms
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of all search synonyms
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonymsResponse"
        '404':
          description: Search synonyms was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/synonyms/{synonymId}:
    get:
      tags:
        - synonyms
      summary: Retrieve a single search synonym
      description: Retrieve the details of a search synonym, given its id.
      operationId: getSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The id of the search synonym
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Search synonym fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonym"
        '404':
          description: Search synonym was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    put:
      tags:
        - synonyms
      summary: Create or update a synonym
      description: Create or update a synonym  to define search terms that should be considered equivalent.
      operationId: upsertSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The ID of the search synonym to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The search synonym object to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchSynonymSchema"
        required: true
      responses:
        '200':
          description: Created/updated search synonym
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonym"
        '404':
          description: Search synonym was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - synonyms
      summary: Delete a synonym associated with a collection
      operationId: deleteSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The ID of the search synonym to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The ID of the deleted search synonym
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonymDeleteResponse"
        '404':
          description: Search synonym not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /collections/{collectionName}/documents/export:
    get:
      tags:
        - documents
      summary: Export all documents in a collection
      description: Export all documents in a collection in JSON lines format.
      operationId: exportDocuments
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: exportDocumentsParameters
          in: query
          schema:
            type: object
            properties:
              filter_by:
                description:
                  Filter conditions for refining your search results. Separate
                  multiple conditions with &&.
                type: string
              include_fields:
                description: List of fields from the document to include in the search result
                type: string
              exclude_fields:
                description: List of fields from the document to exclude in the search result
                type: string

      responses:
        '200':
          description: Exports all the documents in a given collection.
          content:
            application/octet-stream:
              schema:
                type: string
                example: |
                  {"id": "124", "company_name": "Stark Industries", "num_employees": 5215, "country": "US"}
                  {"id": "125", "company_name": "Future Technology", "num_employees": 1232,"country": "UK"}
                  {"id": "126", "company_name": "Random Corp.", "num_employees": 531,"country": "AU"}
        '404':
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents/import:
    post:
      tags:
        - documents
      summary: Import documents into a collection
      description:
        The documents to be imported must be formatted in a newline delimited
        JSON structure. You can feed the output file from a Typesense export operation
        directly as import.
      operationId: importDocuments
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        # Do not change the index position of this param
        - name: importDocumentsParameters
          in: query
          schema:
            type: object
            properties:
              batch_size:
                type: integer
              return_id:
                type: boolean
                description:
                  Returning the id of the imported documents. If you want the
                  import response to return the ingested document's id in the
                  response, you can use the return_id parameter.
              remote_embedding_batch_size:
                type: integer
              return_doc:
                type: boolean
              action:
                $ref: "#/components/schemas/IndexAction"
              dirty_values:
                $ref: "#/components/schemas/DirtyValues"
      requestBody:
        description: The json array of documents or the JSONL file to import
        content:
          application/octet-stream:
            schema:
              type: string
              description: The JSONL file to import
        required: true
      responses:
        '200':
          description:
            Result of the import operation. Each line of the response indicates the result
            of each document present in the request body (in the same order). If the import
            of a single document fails, it does not affect the other documents.
            If there is a failure, the response line will include a corresponding error
            message and as well as the actual document content.
          content:
            application/octet-stream:
              schema:
                type: string
                example: |
                  {"success": true}
                  {"success": false, "error": "Bad JSON.", "document": "[bad doc"}
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '404':
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents/{documentId}:
    get:
      tags:
        - documents
      summary: Retreive a document
      description: Fetch an individual document from a collection by using its ID.
      operationId: getDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          description: The Document ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The document referenced by the ID
          content:
            application/json:
              schema:
                type: object
                description: Can be any key-value pair
        '404':
          description: The document or collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    patch:
      tags:
        - documents
      summary: Update a document
      description:
        Update an individual document from a collection by using its ID.
        The update can be partial.
      operationId: updateDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          description: The Document ID
          required: true
          schema:
            type: string
        - name: dirty_values
          in: query
          description: Dealing with Dirty Data
          schema:
            $ref: "#/components/schemas/DirtyValues"
      requestBody:
        description: The document object with fields to be updated
        content:
          application/json:
            schema:
              type: object
              description: Can be any key-value pair
              x-go-type: "interface{}"
        required: true
      responses:
        '200':
          description: The document referenced by the ID was updated
          content:
            application/json:
              schema:
                type: object
                description: Can be any key-value pair
        '404':
          description: The document or collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - documents
      summary: Delete a document
      description: Delete an individual document from a collection by using its ID.
      operationId: deleteDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          description: The Document ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The document referenced by the ID was deleted
          content:
            application/json:
              schema:
                type: object
                description: Can be any key-value pair
        '404':
          description: The document or collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /conversations/models:
    get:
      description: Retrieve all conversation models
      operationId: retrieveAllConversationModels
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ConversationModelSchema'
                type: array
                x-go-type: '[]*ConversationModelSchema'
          description: List of all conversation models
      summary: List all conversation models
      tags:
        - conversations
    post:
      description: Create a Conversation Model
      operationId: createConversationModel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationModelCreateSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationModelSchema'
          description: Created Conversation Model
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Bad request, see error message for details
      tags:
        - conversations
  /conversations/models/{modelId}:
    get:
      description: Retrieve a conversation model
      operationId: retrieveConversationModel
      parameters:
        - name: modelId
          in: path
          description: The id of the conversation model to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationModelSchema'
          description: A conversation model
      summary: Retrieve a conversation model
      tags:
        - conversations
    put:
      description: Update a conversation model
      operationId: updateConversationModel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationModelUpdateSchema'
        required: true
      parameters:
        - name: modelId
          in: path
          description: The id of the conversation model to update
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationModelSchema'
          description: The conversation model was successfully updated
      summary: Update a conversation model
      tags:
        - conversations
    delete:
      description: Delete a conversation model
      operationId: deleteConversationModel
      parameters:
        - name: modelId
          in: path
          description: The id of the conversation model to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationModelSchema'
          description: The conversation model was successfully deleted
      summary: Delete a conversation model
      tags:
        - conversations
  /keys:
    get:
      tags:
        - keys
      summary: Retrieve (metadata about) all keys.
      operationId: getKeys
      responses:
        '200':
          description: List of all keys
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeysResponse"
    post:
      tags:
        - keys
      summary: Create an API Key
      description:
        Create an API Key with fine-grain access control. You can restrict access
        on both a per-collection and per-action level.
        The generated key is returned only during creation. You want to store
        this key carefully in a secure place.
      operationId: createKey
      requestBody:
        description: The object that describes API key scope
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeySchema"
      responses:
        '201':
          description: Created API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '409':
          description: API key generation conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /keys/{keyId}:
    get:
      tags:
        - keys
      summary: Retrieve (metadata about) a key
      description:
        Retrieve (metadata about) a key. Only the key prefix is returned
        when you retrieve a key. Due to security reasons, only the create endpoint
        returns the full API key.
      operationId: getKey
      parameters:
        - name: keyId
          in: path
          description: The ID of the key to retrieve
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The key referenced by the ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        '404':
          description: The key was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - keys
      summary: Delete an API key given its ID.
      operationId: deleteKey
      parameters:
        - name: keyId
          in: path
          description: The ID of the key to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The key referenced by the ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyDeleteResponse"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '404':
          description: Key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /aliases:
    get:
      tags:
        - collections
      summary: List all aliases
      description: List all aliases and the corresponding collections that they map to.
      operationId: getAliases
      responses:
        '200':
          description: List of all collection aliases
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionAliasesResponse"
  /aliases/{aliasName}:
    put:
      tags:
        - collections
      summary: Create or update a collection alias
      description:
        Create or update a collection alias. An alias is a virtual collection name that points
        to a real collection. If you're familiar with symbolic links on Linux, it's very similar
        to that. Aliases are useful when you want to reindex your data in the
        background on a new collection and switch your application to it without any changes to
        your code.
      operationId: upsertAlias
      parameters:
        - name: aliasName
          in: path
          description: The name of the alias to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: Collection alias to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionAliasSchema"
      responses:
        '200':
          description: The collection alias was created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionAlias"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        '404':
          description: Alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - collections
      summary: Retrieve an alias
      description: Find out which collection an alias points to by fetching it
      operationId: getAlias
      parameters:
        - name: aliasName
          in: path
          description: The name of the alias to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection alias fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionAlias"
        '404':
          description: The alias was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - collections
      summary: Delete an alias
      operationId: deleteAlias
      parameters:
        - name: aliasName
          in: path
          description: The name of the alias to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection alias was deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionAlias"
        '404':
          description: Alias not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /debug:
    get:
      tags:
        - debug
      summary: Print debugging information
      description: Print debugging information
      operationId: debug
      responses:
        '200':
          description: Debugging information
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
  /health:
    get:
      tags:
        - health
      summary: Checks if Typesense server is ready to accept requests.
      description: Checks if Typesense server is ready to accept requests.
      operationId: health
      responses:
        '200':
          description: Search service is ready for requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
  /operations/schema_changes:
    get:
      tags:
        - operations
      summary: Get the status of in-progress schema change operations
      description: Returns the status of any ongoing schema change operations. If no schema changes are in progress, returns an empty response.
      operationId: getSchemaChanges
      responses:
        '200':
          description: List of schema changes in progress
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SchemaChangeStatus"
  /operations/snapshot:
    post:
      tags:
        - operations
      summary: Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
      description:
        Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
        You can then backup the snapshot directory that gets created and later restore it
        as a data directory, as needed.
      operationId: takeSnapshot
      parameters:
        - name: snapshot_path
          in: query
          description: The directory on the server where the snapshot should be saved.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Snapshot is created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /operations/vote:
    post:
      tags:
        - operations
      summary: Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
      description:
        Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
        The follower node that you run this operation against will become the new leader,
        once this command succeeds.
      operationId: vote
      responses:
        '200':
          description: Re-election is performed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /multi_search:
    post:
      operationId: multiSearch
      tags:
        - documents
      summary: send multiple search requests in a single HTTP request
      description:
        This is especially useful to avoid round-trip network latencies incurred otherwise if each of these requests are sent in separate HTTP requests.
        You can also use this feature to do a federated search across multiple collections in a single HTTP request.
      parameters:
        - name: multiSearchParameters
          required: true
          in: query
          schema:
            $ref: "#/components/schemas/MultiSearchParameters"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultiSearchSearchesParameter"
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiSearchResult"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /analytics/events:
    post:
      tags:
        - analytics
      summary: Create an analytics event
      description: Sending events for analytics e.g rank search results based on popularity.
      operationId: createAnalyticsEvent
      requestBody:
        description: The Analytics event to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsEventCreateSchema'
        required: true
      responses:
        '201':
          description: Analytics event successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsEventCreateResponse'
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /analytics/rules:
    post:
      tags:
        - analytics
      summary: Creates an analytics rule
      description:
        When an analytics rule is created, we give it a name and describe the type, the source collections and the destination collection.
      operationId: createAnalyticsRule
      requestBody:
        description: The Analytics rule to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyticsRuleSchema"
        required: true
      responses:
        '201':
          description: Analytics rule successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRuleSchema"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - analytics
      summary: Retrieves all analytics rules
      description:
        Retrieve the details of all analytics rules
      operationId: retrieveAnalyticsRules
      responses:
        '200':
          description: Analytics rules fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRulesRetrieveSchema"
  /analytics/rules/{ruleName}:
    put:
      tags:
        - analytics
      summary: Upserts an analytics rule
      description:
        Upserts an analytics rule with the given name.
      operationId: upsertAnalyticsRule
      parameters:
        - in: path
          name: ruleName
          description: The name of the analytics rule to upsert
          schema:
            type: string
          required: true
      requestBody:
        description: The Analytics rule to be upserted
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyticsRuleUpsertSchema"
        required: true
      responses:
        '200':
          description: Analytics rule successfully upserted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRuleSchema"
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - analytics
      summary: Retrieves an analytics rule
      description:
        Retrieve the details of an analytics rule, given it's name
      operationId: retrieveAnalyticsRule
      parameters:
        - in: path
          name: ruleName
          description: The name of the analytics rule to retrieve
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Analytics rule fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRuleSchema"
        '404':
          description: Analytics rule not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - analytics
      summary: Delete an analytics rule
      description:
        Permanently deletes an analytics rule, given it's name
      operationId: deleteAnalyticsRule
      parameters:
        - in: path
          name: ruleName
          description: The name of the analytics rule to delete
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Analytics rule deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRuleDeleteResponse"
        '404':
          description: Analytics rule not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /metrics.json:
    get:
      tags:
        - operations
      summary: Get current RAM, CPU, Disk & Network usage metrics.
      description:
        Retrieve the metrics.
      operationId: retrieveMetrics
      responses:
        '200':
          description: Metrics fetched.
          content:
            application/json:
              schema:
                type: object
  /stats.json:
    get:
      tags:
        - operations
      summary: Get stats about API endpoints.
      description:
        Retrieve the stats about API endpoints.
      operationId: retrieveAPIStats
      responses:
        '200':
          description: Stats fetched.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIStatsResponse"
  /stopwords:
    get:
      tags:
        - stopwords
      summary: Retrieves all stopwords sets.
      description:
        Retrieve the details of all stopwords sets
      operationId: retrieveStopwordsSets
      responses:
        '200':
          description: Stopwords sets fetched.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StopwordsSetsRetrieveAllSchema"
  /stopwords/{setId}:
    put:
      tags:
        - stopwords
      summary: Upserts a stopwords set.
      description:
        When an analytics rule is created, we give it a name and describe the type, the source collections and the destination collection.
      operationId: upsertStopwordsSet
      parameters:
        - in: path
          name: setId
          description: The ID of the stopwords set to upsert.
          schema:
            type: string
          required: true
          example: countries
      requestBody:
        description: The stopwords set to upsert.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StopwordsSetUpsertSchema"
        required: true
      responses:
        '200':
          description: Stopwords set successfully upserted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StopwordsSetSchema"
        '400':
          description: Bad request, see error message for details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - stopwords
      summary: Retrieves a stopwords set.
      description:
        Retrieve the details of a stopwords set, given it's name.
      operationId: retrieveStopwordsSet
      parameters:
        - in: path
          name: setId
          description: The ID of the stopwords set to retrieve.
          schema:
            type: string
          required: true
          example: countries
      responses:
        '200':
          description: Stopwords set fetched.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StopwordsSetRetrieveSchema"
        '404':
          description: Stopwords set not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - stopwords
      summary: Delete a stopwords set.
      description:
        Permanently deletes a stopwords set, given it's name.
      operationId: deleteStopwordsSet
      parameters:
        - in: path
          name: setId
          description: The ID of the stopwords set to delete.
          schema:
            type: string
          required: true
          example: countries
      responses:
        '200':
          description: Stopwords set rule deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                required:
                  - id
                example: |
                  {"id": "countries"}
        '404':
          description: Stopwords set not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /presets:
    get:
      tags:
        - presets
      summary: Retrieves all presets.
      description: Retrieve the details of all presets
      operationId: retrieveAllPresets
      responses:
        '200':
          description: Presets fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresetsRetrieveSchema'
  /presets/{presetId}:
    get:
      tags:
        - presets
      summary: Retrieves a preset.
      description: Retrieve the details of a preset, given it's name.
      operationId: retrievePreset
      parameters:
        - in: path
          name: presetId
          description: The ID of the preset to retrieve.
          schema:
            type: string
          required: true
          example: listing_view
      responses:
        '200':
          description: Preset fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresetSchema'
        '404':
          description: Preset not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    put:
      tags:
        - presets
      summary: Upserts a preset.
      description: Create or update an existing preset.
      operationId: upsertPreset
      parameters:
        - in: path
          name: presetId
          description: The name of the preset set to upsert.
          schema:
            type: string
          required: true
          example: listing_view
      requestBody:
        description: The stopwords set to upsert.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresetUpsertSchema'
        required: true
      responses:
        '200':
          description: Preset successfully upserted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresetSchema'
        '400':
          description: Bad request, see error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    delete:
      tags:
        - presets
      summary: Delete a preset.
      description: Permanently deletes a preset, given it's name.
      operationId: deletePreset
      parameters:
        - in: path
          name: presetId
          description: The ID of the preset to delete.
          schema:
            type: string
          required: true
          example: listing_view
      responses:
        '200':
          description: Preset deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresetDeleteSchema'
        '404':
          description: Preset not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /stemming/dictionaries:
    get:
      tags:
        - stemming
      summary: List all stemming dictionaries
      description: Retrieve a list of all available stemming dictionaries.
      operationId: listStemmingDictionaries
      responses:
        '200':
          description: List of all dictionaries
          content:
            application/json:
              schema:
                type: object
                properties:
                  dictionaries:
                    type: array
                    items:
                      type: string
                    example: ["irregular-plurals", "company-terms"]

  /stemming/dictionaries/{dictionaryId}:
    get:
      tags:
        - stemming
      summary: Retrieve a stemming dictionary
      description: Fetch details of a specific stemming dictionary.
      operationId: getStemmingDictionary
      parameters:
        - name: dictionaryId
          in: path
          description: The ID of the dictionary to retrieve
          required: true
          schema:
            type: string
          example: irregular-plurals
      responses:
        '200':
          description: Stemming dictionary details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StemmingDictionary"
        '404':
          description: Dictionary not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /stemming/dictionaries/import:
    post:
      tags:
        - stemming
      summary: Import a stemming dictionary
      description: Upload a JSONL file containing word mappings to create or update a stemming dictionary.
      operationId: importStemmingDictionary
      parameters:
        - name: id
          in: query
          description: The ID to assign to the dictionary
          required: true
          schema:
            type: string
          example: irregular-plurals
      requestBody:
        description: The JSONL file containing word mappings
        required: true
        content:
          application/json:
            schema:
              type: string
              example: |
                {"word": "people", "root": "person"}
                {"word": "children", "root": "child"}
      responses:
        '200':
          description: Dictionary successfully imported
          content:
            application/octet-stream:
              schema:
                type: string
                example: >
                  {"word": "people", "root": "person"}
                  {"word": "children", "root": "child"}
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
components:
  schemas:
    CollectionSchema:
      required:
        - name
        - fields
      type: object
      properties:
        name:
          type: string
          description: Name of the collection
          example: companies
        fields:
          type: array
          description: A list of fields for querying, filtering and faceting
          example:
            - name: num_employees
              type: int32
              facet: false
            - name: company_name
              type: string
              facet: false
            - name: country
              type: string
              facet: true
          items:
            $ref: "#/components/schemas/Field"
        default_sorting_field:
          type: string
          description:
            The name of an int32 / float field that determines the order in which
            the search results are ranked when a sort_by clause is not provided during
            searching. This field must indicate some kind of popularity.
          example: num_employees # Go with the first field name listed above to produce sane defaults
          default: ""
        token_separators:
          type: array
          description: >
            List of symbols or special characters to be used for
            splitting the text into individual words in addition to space and new-line characters.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
        enable_nested_fields:
          type: boolean
          description:
            Enables experimental support at a collection level for nested object or object array fields.
            This field is only available if the Typesense server is version `0.24.0.rcn34` or later.
          default: false
          example: true
        symbols_to_index:
          type: array
          description: >
            List of symbols or special characters to be indexed.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
        voice_query_model:
          $ref: "#/components/schemas/VoiceQueryModelCollectionConfig"
    CollectionUpdateSchema:
      required:
        - fields
      type: object
      properties:
        fields:
          type: array
          description: A list of fields for querying, filtering and faceting
          example:
            - name: company_name
              type: string
              facet: false
            - name: num_employees
              type: int32
              facet: false
            - name: country
              type: string
              facet: true
          items:
            $ref: "#/components/schemas/Field"
    CollectionResponse:
      allOf:
        - $ref: "#/components/schemas/CollectionSchema"
        - type: object
          required:
            - num_documents
            - created_at
          properties:
            num_documents:
              type: integer
              description: Number of documents in the collection
              format: int64
              readOnly: true
            created_at:
              type: integer
              description: Timestamp of when the collection was created (Unix epoch in seconds)
              format: int64
              readOnly: true
    Field:
      required:
        - name
        - type
      type: object
      properties:
        name:
          type: string
          example: company_name
        type:
          type: string
          example: string
        optional:
          type: boolean
          example: true
        facet:
          type: boolean
          example: false
        index:
          type: boolean
          example: true
          default: true
        locale:
          type: string
          example: el
        sort:
          type: boolean
          example: true
        infix:
          type: boolean
          example: true
          default: false
        reference:
          type: string
          description: >
            Name of a field in another collection that should be linked to this collection so that it can be joined during query.
        num_dim:
          type: integer
          example: 256
        drop:
          type: boolean
          example: true
          # omitting default value since we want it to be null
        store:
          type: boolean
          description: >
            When set to false, the field value will not be stored on disk. Default: true.
        vec_dist:
          type: string
          description: >
            The distance metric to be used for vector search. Default: `cosine`. You can also use `ip` for inner product.
        range_index:
          type: boolean
          description: >
            Enables an index optimized for range filtering on numerical fields (e.g. rating:>3.5). Default: false.
        stem:
          type: boolean
          description: >
            Values are stemmed before indexing in-memory. Default: false.
        stem_dictionary:
          type: string
          description: Name of the stemming dictionary to use for this field
          example: irregular-plurals
        token_separators:
          type: array
          description: >
            List of symbols or special characters to be used for
            splitting the text into individual words in addition to space and new-line characters.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
        symbols_to_index:
          type: array
          description: >
            List of symbols or special characters to be indexed.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
        embed:
          type: object
          required:
            - from
            - model_config
          properties:
            from:
              type: array
              items:
                type: string
            model_config:
              type: object
              required:
                - model_name
              properties:
                model_name:
                  type: string
                api_key:
                  type: string
                url:
                  type: string
                access_token:
                  type: string
                refresh_token:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
                project_id:
                  type: string
                indexing_prefix:
                  type: string
                query_prefix:
                  type: string
    VoiceQueryModelCollectionConfig:
      type: object
      description: >
        Configuration for the voice query model
      properties:
        model_name:
          type: string
          example: "ts/whisper/base.en"
    CollectionAliasSchema:
      type: object
      required:
        - collection_name
      properties:
        collection_name:
          type: string
          description: Name of the collection you wish to map the alias to
    CollectionAlias:
      type: object
      required:
        - collection_name
        - name
      properties:
        name:
          type: string
          readOnly: true
          description: Name of the collection alias
        collection_name:
          type: string
          description: Name of the collection the alias mapped to
    CollectionAliasesResponse:
      type: object
      required:
        - aliases
      properties:
        aliases:
          type: array
          x-go-type: "[]*CollectionAlias"
          items:
            $ref: "#/components/schemas/CollectionAlias"
    SearchResult:
      type: object
      properties:
        facet_counts:
          type: array
          items:
            $ref: "#/components/schemas/FacetCounts"
        found:
          type: integer
          description: The number of documents found
        found_docs:
          type: integer
        search_time_ms:
          type: integer
          description: The number of milliseconds the search took
        out_of:
          type: integer
          description: The total number of documents in the collection
        search_cutoff:
          type: boolean
          description: Whether the search was cut off
        page:
          type: integer
          description: The search result page number
        grouped_hits:
          type: array
          items:
            $ref: "#/components/schemas/SearchGroupedHit"
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
        request_params:
          type: object
          required:
            - collection_name
            - q
            - per_page
          properties:
            collection_name:
              type: string
            q:
              type: string
            per_page:
              type: integer
            voice_query:
              type: object
              properties:
                transcribed_query:
                  type: string
        conversation:
          $ref: "#/components/schemas/SearchResultConversation"
    SearchResultConversation:
      type: object
      required:
        - answer
        - conversation_history
        - conversation_id
        - query
      properties:
        answer:
          type: string
        conversation_history:
          type: array
          items:
            type: object
        conversation_id:
          type: string
        query:
          type: string
    SearchGroupedHit:
      type: object
      required:
        - group_key
        - hits
      properties:
        found:
          type: integer
        group_key:
          type: array
          items: {}
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
    SearchResultHit:
      type: object
      properties:
        highlights:
          type: array
          description: (Deprecated) Contains highlighted portions of the search fields
          items:
            $ref: "#/components/schemas/SearchHighlight"
        highlight:
          type: object
          description: Highlighted version of the matching document
          additionalProperties: true
        document:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: object
        text_match:
          type: integer
          format: int64
        text_match_info:
          type: object
          properties:
            best_field_score:
              type: string
            best_field_weight:
              type: integer
            fields_matched:
              type: integer
            num_tokens_dropped:
              type: integer
            score:
              type: string
            tokens_matched:
              type: integer
            typo_prefix_score:
              type: integer
        geo_distance_meters:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: integer
        vector_distance:
          type: number
          format: float
          description: Distance between the query vector and matching document's vector value
      example:
        highlights:
          company_name:
            field: company_name
            snippet: <mark>Stark</mark> Industries
        document:
          id: "124"
          company_name: Stark Industries
          num_employees: 5215
          country: USA
        text_match: 1234556
    SearchHighlight:
      type: object
      properties:
        field:
          type: string
          example: company_name
        snippet:
          type: string
          description: Present only for (non-array) string fields
          example: <mark>Stark</mark> Industries
        snippets:
          type: array
          description: Present only for (array) string[] fields
          example:
            - <mark>Stark</mark> Industries
            - <mark>Stark</mark> Corp
          items:
            type: string
        value:
          type: string
          description: Full field value with highlighting, present only for (non-array) string fields
          example: <mark>Stark</mark> Industries is a major supplier of space equipment.
        values:
          type: array
          description: Full field value with highlighting, present only for (array) string[] fields
          example:
            - <mark>Stark</mark> Industries
            - <mark>Stark</mark> Corp
          items:
            type: string
        indices:
          type: array
          description: The indices property will be present only for string[]
            fields and will contain the corresponding indices of the snippets
            in the search field
          example: 1
          items:
            type: integer
        matched_tokens:
          type: array
          items:
            type: object
            x-go-type: "interface{}"
    SearchOverrideSchema:
      type: object
      required:
        - rule
      properties:
        rule:
          $ref: "#/components/schemas/SearchOverrideRule"
        includes:
          type: array
          description:
            List of document `id`s that should be included in the search results with their
            corresponding `position`s.
          items:
            $ref: "#/components/schemas/SearchOverrideInclude"
        excludes:
          type: array
          description: List of document `id`s that should be excluded from the search results.
          items:
            $ref: "#/components/schemas/SearchOverrideExclude"
        filter_by:
          type: string
          description: >
            A filter by clause that is applied to any search query that matches the override rule.
        remove_matched_tokens:
          type: boolean
          description: >
            Indicates whether search query tokens that exist in the override's rule should be removed from the search query.
        metadata:
          type: object
          description: >
            Return a custom JSON object in the Search API response, when this rule is triggered. This can can be used to display a pre-defined message (eg: a promotion banner) on the front-end when a particular rule is triggered.
        sort_by:
          type: string
          description: >
            A sort by clause that is applied to any search query that matches the override rule.
        replace_query:
          type: string
          description: >
            Replaces the current search query with this value, when the search query matches the override rule.
        filter_curated_hits:
          type: boolean
          description: >
            When set to true, the filter conditions of the query is applied to the curated records as well.
            Default: false.
        effective_from_ts:
          type: integer
          description: >
            A Unix timestamp that indicates the date/time from which the override will be active. You can use this to create override rules that start applying from a future point in time.
        effective_to_ts:
          type: integer
          description: >
            A Unix timestamp that indicates the date/time until which the override will be active. You can use this to create override rules that stop applying after a period of time.
        stop_processing:
          type: boolean
          description: >
            When set to true, override processing will stop at the first matching rule. When set to false override processing will continue and multiple override actions will be triggered in sequence.
            Overrides are processed in the lexical sort order of their id field.
            Default: true.
    SearchOverride:
      allOf:
        - $ref: "#/components/schemas/SearchOverrideSchema"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              readOnly: true
    SearchOverrideDeleteResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The id of the override that was deleted
    SearchOverrideRule:
      type: object
      properties:
        tags:
          type: array
          description: List of tag values to associate with this override rule.
          items:
            type: string
        query:
          type: string
          description: Indicates what search queries should be overridden
        match:
          type: string
          description: >
            Indicates whether the match on the query term should be `exact` or `contains`.
            If we want to match all queries that contained
            the word `apple`, we will use the `contains` match instead.
          enum:
            - exact
            - contains
        filter_by:
          type: string
          description: >
            Indicates that the override should apply when the filter_by parameter in a search query exactly matches the string specified here (including backticks, spaces, brackets, etc).
    SearchOverrideInclude:
      type: object
      required:
        - id
        - position
      properties:
        id:
          type: string
          description: document id that should be included
        position:
          type: integer
          description: position number where document should be included in the search results
    SearchOverrideExclude:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: document id that should be excluded from the search results.
    SearchOverridesResponse:
      type: object
      required:
        - overrides
      properties:
        overrides:
          type: array
          x-go-type: "[]*SearchOverride"
          items:
            $ref: "#/components/schemas/SearchOverride"
    SearchSynonymSchema:
      type: object
      required:
        - synonyms
      properties:
        root:
          type: string
          description: For 1-way synonyms, indicates the root word that words in the `synonyms` parameter map to.
        synonyms:
          type: array
          description: Array of words that should be considered as synonyms.
          items:
            type: string
        locale:
          type: string
          description: Locale for the synonym, leave blank to use the standard tokenizer.
        symbols_to_index:
          type: array
          description: By default, special characters are dropped from synonyms. Use this attribute to specify which special characters should be indexed as is.
          items:
            type: string
    SearchSynonym:
      allOf:
        - $ref: "#/components/schemas/SearchSynonymSchema"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              readOnly: true
    SearchSynonymDeleteResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The id of the synonym that was deleted
    SearchSynonymsResponse:
      type: object
      required:
        - synonyms
      properties:
        synonyms:
          type: array
          x-go-type: "[]*SearchSynonym"
          items:
            $ref: "#/components/schemas/SearchSynonym"
    HealthStatus:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
    SchemaChangeStatus:
      type: object
      properties:
        collection:
          type: string
          description: Name of the collection being modified
        validated_docs:
          type: integer
          description: Number of documents that have been validated
        altered_docs:
          type: integer
          description: Number of documents that have been altered
    SuccessStatus:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
    ApiResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ApiKeySchema:
      type: object
      required:
        - actions
        - collections
        - description
      properties:
        value:
          type: string
        description:
          type: string
        actions:
          type: array
          items:
            type: string
        collections:
          type: array
          items:
            type: string
        expires_at:
          type: integer
          format: int64
    ApiKey:
      allOf:
        - $ref: "#/components/schemas/ApiKeySchema"
        - type: object
          properties:
            id:
              type: integer
              format: int64
              readOnly: true
            value_prefix:
              type: string
              readOnly: true
    ApiKeyDeleteResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
          description: The id of the API key that was deleted
    ApiKeysResponse:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          x-go-type: "[]*ApiKey"
          items:
            $ref: "#/components/schemas/ApiKey"
    ScopedKeyParameters:
      type: object
      properties:
        filter_by:
          type: string
        expires_at:
          type: integer
          format: int64
    SnapshotParameters:
      type: object
      properties:
        snapshot_path:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    MultiSearchResult:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/MultiSearchResultItem"
        conversation:
          $ref: "#/components/schemas/SearchResultConversation"
    MultiSearchResultItem:
      allOf:
      - $ref: "#/components/schemas/SearchResult"
      - type: object
        properties:
          code:
            type: integer
            description: HTTP error code
            format: int64
          error:
            type: string
            description: Error description
    SearchParameters:
      type: object
      properties:
        q:
          description: The query text to search for in the collection.
            Use * as the search string to return all documents.
            This is typically useful when used in conjunction with filter_by.
          type: string

        query_by:
          description: A list of `string` fields that should be queried
            against. Multiple fields are separated with a comma.
          type: string

        query_by_weights:
          description:
            The relative weight to give each `query_by` field when ranking results.
            This can be used to boost fields in priority, when looking for matches.
            Multiple fields are separated with a comma.
          type: string

        text_match_type:
          description:
            In a multi-field matching context, this parameter determines how the representative text match
            score of a record is calculated. Possible values are max_score (default) or max_weight.
          type: string

        prefix:
          description:
            Boolean field to indicate that the last word in the query should
            be treated as a prefix, and not as a whole word. This is used for building
            autocomplete and instant search interfaces. Defaults to true.
          type: string

        infix:
          description:
            If infix index is enabled for this field, infix searching can be done on a per-field
            basis by sending a comma separated string parameter called infix to the search query.
            This parameter can have 3 values; `off` infix search is disabled, which is default
            `always` infix search is performed along with regular search
            `fallback` infix search is performed if regular search does not produce results
          type: string

        max_extra_prefix:
          description:
            There are also 2 parameters that allow you to control the extent of infix searching
            max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
            or after the query that can be present in the token. For example query "K2100" has 2 extra
            symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
          type: integer

        max_extra_suffix:
          description:
            There are also 2 parameters that allow you to control the extent of infix searching
            max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
            or after the query that can be present in the token. For example query "K2100" has 2 extra
            symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
          type: integer

        filter_by:
          description:
            Filter conditions for refining youropen api validator search results. Separate
            multiple conditions with &&.
          type: string
          example: "num_employees:>100 && country: [USA, UK]"

        max_filter_by_candidates:
          description:
            Controls the number of similar words that Typesense considers during fuzzy search
            on filter_by values. Useful for controlling prefix matches like company_name:Acm*.
          type: integer

        sort_by:
          description:
            A list of numerical fields and their corresponding sort orders
            that will be used for ordering your results.
            Up to 3 sort fields can be specified.
            The text similarity score is exposed as a special `_text_match` field that
            you can use in the list of sorting fields.
            If no `sort_by` parameter is specified, results are sorted by
            `_text_match:desc,default_sorting_field:desc`
          type: string
          example: num_employees:desc

        facet_by:
          description:
            A list of fields that will be used for faceting your results
            on. Separate multiple fields with a comma.
          type: string

        max_facet_values:
          description: Maximum number of facet values to be returned.
          type: integer

        facet_query:
          description:
            Facet values that are returned can now be filtered via this parameter.
            The matching facet text is also highlighted. For example, when faceting
            by `category`, you can set `facet_query=category:shoe` to return only
            facet values that contain the prefix "shoe".
          type: string

        num_typos:
          description: >
            The number of typographical errors (1 or 2) that would be tolerated.
            Default: 2
          type: string

        page:
          description: Results from this specific page number would be fetched.
          type: integer

        per_page:
          description: "Number of results to fetch per page. Default: 10"
          type: integer

        limit:
          description: >
            Number of hits to fetch. Can be used as an alternative to the per_page parameter.
            Default: 10.
          type: integer

        offset:
          description: Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.
          type: integer

        group_by:
          description:
            You can aggregate search results into groups or buckets by specify
            one or more `group_by` fields. Separate multiple fields with a comma.
            To group on a particular field, it must be a faceted field.
          type: string

        group_limit:
          description: >
            Maximum number of hits to be returned for every group. If the `group_limit` is
            set as `K` then only the top K hits in each group are returned in the response.
            Default: 3
          type: integer

        group_missing_values:
          description: >
            Setting this parameter to true will place all documents that have a null value in the group_by field, into a single group.
            Setting this parameter to false, will cause each document with a null value in the group_by field to not be grouped with other documents.
            Default: true
          type: boolean

        include_fields:
          description: List of fields from the document to include in the search result
          type: string

        exclude_fields:
          description: List of fields from the document to exclude in the search result
          type: string

        highlight_full_fields:
          description: List of fields which should be highlighted fully without snippeting
          type: string

        highlight_affix_num_tokens:
          description: >
            The number of tokens that should surround the highlighted text on each side.
            Default: 4
          type: integer

        highlight_start_tag:
          description: >
            The start tag used for the highlighted snippets.
            Default: `<mark>`
          type: string
        highlight_end_tag:
          description: >
            The end tag used for the highlighted snippets.
            Default: `</mark>`
          type: string

        enable_highlight_v1:
          description: >
            Flag for enabling/disabling the deprecated, old highlight structure in the response.
            Default: true
          type: boolean
          default: true

        snippet_threshold:
          description: >
            Field values under this length will be fully highlighted, instead of showing
            a snippet of relevant portion. Default: 30
          type: integer

        drop_tokens_threshold:
          description: >
            If the number of results found for a specific query is less than
            this number, Typesense will attempt to drop the tokens in the query until
            enough results are found. Tokens that have the least individual hits
            are dropped first. Set to 0 to disable. Default: 10
          type: integer
        drop_tokens_mode:
          $ref: "#/components/schemas/DropTokensMode"
        typo_tokens_threshold:
          description: >
            If the number of results found for a specific query is less than this number,
            Typesense will attempt to look for tokens with more typos until
            enough results are found. Default: 100
          type: integer
        enable_typos_for_alpha_numerical_tokens:
          type: boolean
          description: >
            Set this parameter to false to disable typos on alphanumerical query tokens. Default: true.

        filter_curated_hits:
          type: boolean
          description: >
            Whether the filter_by condition of the search query should be applicable to curated results (override definitions, pinned hits, hidden hits, etc.). Default: false
        enable_synonyms:
          type: boolean
          description: >
            If you have some synonyms defined but want to disable all of them for a particular search query, set enable_synonyms to false. Default: true
        synonym_prefix:
          type: boolean
          description: >
            Allow synonym resolution on word prefixes in the query. Default: false
        synonym_num_typos:
          type: integer
          description: >
            Allow synonym resolution on typo-corrected words in the query. Default: 0

        pinned_hits:
          description: >
            A list of records to unconditionally include in the search results
            at specific positions. An example use case would be to feature or promote
            certain items on the top of search results.
            A list of `record_id:hit_position`. Eg: to include a record with ID 123
            at Position 1 and another record with ID 456 at Position 5,
            you'd specify `123:1,456:5`.

            You could also use the Overrides feature to override search results based
            on rules. Overrides are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        hidden_hits:
          description: >
            A list of records to unconditionally hide from search results.
            A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456,
            you'd specify `123,456`.

            You could also use the Overrides feature to override search results based
            on rules. Overrides are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        override_tags:
          description: Comma separated list of tags to trigger the curations rules that match the tags.
          type: string

        highlight_fields:
          description: >
            A list of custom fields that must be highlighted even if you don't query
            for them
          type: string

        split_join_tokens:
          description: >
            Treat space as typo: search for q=basket ball if q=basketball is not found or vice-versa.
            Splitting/joining of tokens will only be attempted if the original query produces no results.
            To always trigger this behavior, set value to `always``.
            To disable, set value to `off`. Default is `fallback`.
          type: string

        pre_segmented_query:
          description: >
            You can index content from any logographic language into Typesense if you
            are able to segment / split the text into space-separated words yourself
            before indexing and querying.

            Set this parameter to true to do the same
          type: boolean

        preset:
          description: >
            Search using a bunch of search parameters by setting this parameter to
            the name of the existing Preset.
          type: string

        enable_overrides:
          description: >
            If you have some overrides defined but want to disable all of them during
            query time, you can do that by setting this parameter to false
          type: boolean
          default: false

        prioritize_exact_match:
          description: >
            Set this parameter to true to ensure that an exact match is ranked above
            the others
          type: boolean
          default: true
        max_candidates:
          description: >
            Control the number of words that Typesense considers for typo and prefix searching.
          type: integer
        prioritize_token_position:
          description: >
            Make Typesense prioritize documents where the query words appear earlier in the text.
          type: boolean
          default: false
        prioritize_num_matching_fields:
          description: >
            Make Typesense prioritize documents where the query words appear in more number of fields.
          type: boolean
          default: true
        enable_typos_for_numerical_tokens:
          description: >
            Make Typesense disable typos for numerical tokens.
          type: boolean
          default: true
        exhaustive_search:
          description: >
            Setting this to true will make Typesense consider all prefixes and typo
            corrections of the words in the query without stopping early when enough results are found
            (drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
          type: boolean
        search_cutoff_ms:
          description: >
            Typesense will attempt to return results early if the cutoff time has elapsed.
            This is not a strict guarantee and facet computation is not bound by this parameter.
          type: integer
        use_cache:
          description: >
            Enable server side caching of search query results. By default, caching is disabled.
          type: boolean
        cache_ttl:
          description: >
            The duration (in seconds) that determines how long the search query is cached.
            This value can be set on a per-query basis. Default: 60.
          type: integer
        min_len_1typo:
          description: >
            Minimum word length for 1-typo correction to be applied.
            The value of num_typos is still treated as the maximum allowed typos.
          type: integer
        min_len_2typo:
          description: >
            Minimum word length for 2-typo correction to be applied.
            The value of num_typos is still treated as the maximum allowed typos.
          type: integer
        vector_query:
          description: >
            Vector query expression for fetching documents "closest" to a given query/document vector.
          type: string
        remote_embedding_timeout_ms:
          description: >
            Timeout (in milliseconds) for fetching remote embeddings.
          type: integer
        remote_embedding_num_tries:
          description: >
            Number of times to retry fetching remote embeddings.
          type: integer
        facet_strategy:
          description: >
            Choose the underlying faceting strategy used. Comma separated string of allows values:
            exhaustive, top_values or automatic (default).
          type: string
        stopwords:
          description: >
            Name of the stopwords set to apply for this search,
            the keywords present in the set will be removed from the search query.
          type: string
        facet_return_parent:
          description: >
            Comma separated string of nested facet fields whose parent object should be returned in facet response.
          type: string
        voice_query:
          description: >
            The base64 encoded audio file in 16 khz 16-bit WAV format.
          type: string
        conversation:
          description: >
            Enable conversational search.
          type: boolean
        conversation_model_id:
          description: >
            The Id of Conversation Model to be used.
          type: string
        conversation_id:
          description: >
            The Id of a previous conversation to continue, this tells Typesense to include prior context when communicating with the LLM.
          type: string

    MultiSearchParameters:
      description: >
        Parameters for the multi search API.
      type: object
      properties:
        q:
          description: The query text to search for in the collection.
            Use * as the search string to return all documents.
            This is typically useful when used in conjunction with filter_by.
          type: string

        query_by:
          description: A list of `string` fields that should be queried
            against. Multiple fields are separated with a comma.
          type: string

        query_by_weights:
          description:
            The relative weight to give each `query_by` field when ranking results.
            This can be used to boost fields in priority, when looking for matches.
            Multiple fields are separated with a comma.
          type: string

        text_match_type:
          description:
            In a multi-field matching context, this parameter determines how the representative text match
            score of a record is calculated. Possible values are max_score (default) or max_weight.
          type: string

        prefix:
          description:
            Boolean field to indicate that the last word in the query should
            be treated as a prefix, and not as a whole word. This is used for building
            autocomplete and instant search interfaces. Defaults to true.
          type: string

        infix:
          description:
            If infix index is enabled for this field, infix searching can be done on a per-field
            basis by sending a comma separated string parameter called infix to the search query.
            This parameter can have 3 values; `off` infix search is disabled, which is default
            `always` infix search is performed along with regular search
            `fallback` infix search is performed if regular search does not produce results
          type: string

        max_extra_prefix:
          description:
            There are also 2 parameters that allow you to control the extent of infix searching
            max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
            or after the query that can be present in the token. For example query "K2100" has 2 extra
            symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
          type: integer

        max_extra_suffix:
          description:
            There are also 2 parameters that allow you to control the extent of infix searching
            max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
            or after the query that can be present in the token. For example query "K2100" has 2 extra
            symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
          type: integer

        filter_by:
          description:
            Filter conditions for refining youropen api validator search results. Separate
            multiple conditions with &&.
          type: string
          example: "num_employees:>100 && country: [USA, UK]"

        sort_by:
          description:
            A list of numerical fields and their corresponding sort orders
            that will be used for ordering your results.
            Up to 3 sort fields can be specified.
            The text similarity score is exposed as a special `_text_match` field that
            you can use in the list of sorting fields.
            If no `sort_by` parameter is specified, results are sorted by
            `_text_match:desc,default_sorting_field:desc`
          type: string

        facet_by:
          description:
            A list of fields that will be used for faceting your results
            on. Separate multiple fields with a comma.
          type: string

        max_facet_values:
          description: Maximum number of facet values to be returned.
          type: integer

        facet_query:
          description:
            Facet values that are returned can now be filtered via this parameter.
            The matching facet text is also highlighted. For example, when faceting
            by `category`, you can set `facet_query=category:shoe` to return only
            facet values that contain the prefix "shoe".
          type: string

        num_typos:
          description: >
            The number of typographical errors (1 or 2) that would be tolerated.
            Default: 2
          type: string

        page:
          description: Results from this specific page number would be fetched.
          type: integer

        per_page:
          description: "Number of results to fetch per page. Default: 10"
          type: integer

        limit:
          description: >
            Number of hits to fetch. Can be used as an alternative to the per_page parameter.
            Default: 10.
          type: integer

        offset:
          description: Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.
          type: integer

        group_by:
          description:
            You can aggregate search results into groups or buckets by specify
            one or more `group_by` fields. Separate multiple fields with a comma.
            To group on a particular field, it must be a faceted field.
          type: string

        group_limit:
          description: >
            Maximum number of hits to be returned for every group. If the `group_limit` is
            set as `K` then only the top K hits in each group are returned in the response.
            Default: 3
          type: integer

        group_missing_values:
          description: >
            Setting this parameter to true will place all documents that have a null value in the group_by field, into a single group.
            Setting this parameter to false, will cause each document with a null value in the group_by field to not be grouped with other documents.
            Default: true
          type: boolean

        include_fields:
          description: List of fields from the document to include in the search result
          type: string

        exclude_fields:
          description: List of fields from the document to exclude in the search result
          type: string

        highlight_full_fields:
          description: List of fields which should be highlighted fully without snippeting
          type: string

        highlight_affix_num_tokens:
          description: >
            The number of tokens that should surround the highlighted text on each side.
            Default: 4
          type: integer

        highlight_start_tag:
          description: >
            The start tag used for the highlighted snippets.
            Default: `<mark>`
          type: string
        highlight_end_tag:
          description: >
            The end tag used for the highlighted snippets.
            Default: `</mark>`
          type: string

        snippet_threshold:
          description: >
            Field values under this length will be fully highlighted, instead of showing
            a snippet of relevant portion. Default: 30
          type: integer

        drop_tokens_threshold:
          description: >
            If the number of results found for a specific query is less than
            this number, Typesense will attempt to drop the tokens in the query until
            enough results are found. Tokens that have the least individual hits
            are dropped first. Set to 0 to disable. Default: 10
          type: integer
        drop_tokens_mode:
          $ref: "#/components/schemas/DropTokensMode"
        typo_tokens_threshold:
          description: >
            If the number of results found for a specific query is less than this number,
            Typesense will attempt to look for tokens with more typos until
            enough results are found. Default: 100
          type: integer
        enable_typos_for_alpha_numerical_tokens:
          type: boolean
          description: >
            Set this parameter to false to disable typos on alphanumerical query tokens. Default: true.

        filter_curated_hits:
          type: boolean
          description: >
            Whether the filter_by condition of the search query should be applicable to curated results (override definitions, pinned hits, hidden hits, etc.). Default: false
        enable_synonyms:
          type: boolean
          description: >
            If you have some synonyms defined but want to disable all of them for a particular search query, set enable_synonyms to false. Default: true
        synonym_prefix:
          type: boolean
          description: >
            Allow synonym resolution on word prefixes in the query. Default: false
        synonym_num_typos:
          type: integer
          description: >
            Allow synonym resolution on typo-corrected words in the query. Default: 0

        pinned_hits:
          description: >
            A list of records to unconditionally include in the search results
            at specific positions. An example use case would be to feature or promote
            certain items on the top of search results.
            A list of `record_id:hit_position`. Eg: to include a record with ID 123
            at Position 1 and another record with ID 456 at Position 5,
            you'd specify `123:1,456:5`.

            You could also use the Overrides feature to override search results based
            on rules. Overrides are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        hidden_hits:
          description: >
            A list of records to unconditionally hide from search results.
            A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456,
            you'd specify `123,456`.

            You could also use the Overrides feature to override search results based
            on rules. Overrides are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        override_tags:
          description: Comma separated list of tags to trigger the curations rules that match the tags.
          type: string

        highlight_fields:
          description: >
            A list of custom fields that must be highlighted even if you don't query
            for them
          type: string

        pre_segmented_query:
          description: >
            You can index content from any logographic language into Typesense if you
            are able to segment / split the text into space-separated words yourself
            before indexing and querying.

            Set this parameter to true to do the same
          type: boolean
          default: false

        preset:
          description: >
            Search using a bunch of search parameters by setting this parameter to
            the name of the existing Preset.
          type: string

        enable_overrides:
          description: >
            If you have some overrides defined but want to disable all of them during
            query time, you can do that by setting this parameter to false
          type: boolean
          default: false

        prioritize_exact_match:
          description: >
            Set this parameter to true to ensure that an exact match is ranked above
            the others
          type: boolean
          default: true

        prioritize_token_position:
          description: >
            Make Typesense prioritize documents where the query words appear earlier in the text.
          type: boolean
          default: false

        prioritize_num_matching_fields:
          description: >
            Make Typesense prioritize documents where the query words appear in more number of fields.
          type: boolean
          default: true

        enable_typos_for_numerical_tokens:
          description: >
            Make Typesense disable typos for numerical tokens.
          type: boolean
          default: true

        exhaustive_search:
          description: >
            Setting this to true will make Typesense consider all prefixes and typo
            corrections of the words in the query without stopping early when enough results are found
            (drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
          type: boolean
        search_cutoff_ms:
          description: >
            Typesense will attempt to return results early if the cutoff time has elapsed.
            This is not a strict guarantee and facet computation is not bound by this parameter.
          type: integer
        use_cache:
          description: >
            Enable server side caching of search query results. By default, caching is disabled.
          type: boolean
        cache_ttl:
          description: >
            The duration (in seconds) that determines how long the search query is cached.
            This value can be set on a per-query basis. Default: 60.
          type: integer
        min_len_1typo:
          description: >
            Minimum word length for 1-typo correction to be applied.
            The value of num_typos is still treated as the maximum allowed typos.
          type: integer
        min_len_2typo:
          description: >
            Minimum word length for 2-typo correction to be applied.
            The value of num_typos is still treated as the maximum allowed typos.
          type: integer
        vector_query:
          description: >
            Vector query expression for fetching documents "closest" to a given query/document vector.
          type: string
        remote_embedding_timeout_ms:
          description: >
            Timeout (in milliseconds) for fetching remote embeddings.
          type: integer
        remote_embedding_num_tries:
          description: >
            Number of times to retry fetching remote embeddings.
          type: integer
        facet_strategy:
          description: >
            Choose the underlying faceting strategy used. Comma separated string of allows values:
            exhaustive, top_values or automatic (default).
          type: string
        stopwords:
          description: >
            Name of the stopwords set to apply for this search,
            the keywords present in the set will be removed from the search query.
          type: string
        facet_return_parent:
          description: >
            Comma separated string of nested facet fields whose parent object should be returned in facet response.
          type: string
        voice_query:
          description: >
            The base64 encoded audio file in 16 khz 16-bit WAV format.
          type: string
        conversation:
          description: >
            Enable conversational search.
          type: boolean
        conversation_model_id:
          description: >
            The Id of Conversation Model to be used.
          type: string
        conversation_id:
          description: >
            The Id of a previous conversation to continue, this tells Typesense to include prior context when communicating with the LLM.
          type: string
    MultiSearchSearchesParameter:
      type: object
      required:
        - searches
      properties:
        union:
          type: boolean
          description: When true, merges the search results from each search query into a single ordered set of hits.
        searches:
          type: array
          items:
            $ref: "#/components/schemas/MultiSearchCollectionParameters"
    MultiSearchCollectionParameters:
      allOf:
        - $ref: "#/components/schemas/MultiSearchParameters"
        - type: object
          properties:
            collection:
              type: string
              description: >
                The collection to search in.
            x-typesense-api-key:
              type: string
              description: A separate search API key for each search within a multi_search request
            rerank_hybrid_matches:
              type: boolean
              description: >
                When true, computes both text match and vector distance scores for all matches in hybrid search.
                Documents found only through keyword search will get a vector distance score, and
                documents found only through vector search will get a text match score.
              default: false
    FacetCounts:
      type: object
      properties:
        counts:
          type: array
          items:
            type: object
            properties:
              count:
                type: integer
              highlighted:
                type: string
              value:
                type: string
              parent:
                type: object
        field_name:
          type: string
        stats:
          type: object
          properties:
            max:
              type: number
              format: double
            min:
              type: number
              format: double
            sum:
              type: number
              format: double
            total_values:
              type: integer
            avg:
              type: number
              format: double
    AnalyticsEventCreateResponse:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
    AnalyticsEventCreateSchema:
      type: object
      required:
        - type
        - name
        - data
      properties:
        type:
          type: string
        name:
          type: string
        data:
          type: object
    AnalyticsRuleUpsertSchema:
      type: object
      required:
        - type
        - params
      properties:
        type:
          type: string
          enum:
            - popular_queries
            - nohits_queries
            - counter
        params:
          $ref: "#/components/schemas/AnalyticsRuleParameters"
    AnalyticsRuleParameters:
      type: object
      required:
        - source
        - destination
      properties:
        source:
          $ref: '#/components/schemas/AnalyticsRuleParametersSource'
        destination:
          $ref: '#/components/schemas/AnalyticsRuleParametersDestination'
        limit:
          type: integer
        expand_query:
          type: boolean
    AnalyticsRuleParametersSource:
      type: object
      required:
        - collections
      properties:
        collections:
          type: array
          items:
            type: string
        events:
          type: array
          items:
            type: object
            required:
              - type
              - weight
              - name
            properties:
              type:
                type: string
              weight:
                type: number
                format: float
              name:
                type: string
    AnalyticsRuleParametersDestination:
      type: object
      required:
        - collection
      properties:
        collection:
          type: string
        counter_field:
          type: string
    AnalyticsRuleDeleteResponse:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    AnalyticsRuleSchema:
      allOf:
        - $ref: '#/components/schemas/AnalyticsRuleUpsertSchema'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
    AnalyticsRulesRetrieveSchema:
      type: object
      properties:
        rules:
          type: array
          items:
            $ref: "#/components/schemas/AnalyticsRuleSchema"
          x-go-type: '[]*AnalyticsRuleSchema'
    APIStatsResponse:
      type: object
      properties:
        delete_latency_ms:
          type: number
          format: double
        delete_requests_per_second:
          type: number
          format: double
        import_latency_ms:
          type: number
          format: double
        import_requests_per_second:
          type: number
          format: double
        latency_ms:
          type: object
          x-go-type: "map[string]float64"
        overloaded_requests_per_second:
          type: number
          format: double
        pending_write_batches:
          type: number
          format: double
        requests_per_second:
          type: object
          x-go-type: "map[string]float64"
        search_latency_ms:
          type: number
          format: double
        search_requests_per_second:
          type: number
          format: double
        total_requests_per_second:
          type: number
          format: double
        write_latency_ms:
          type: number
          format: double
        write_requests_per_second:
          type: number
          format: double
    StopwordsSetUpsertSchema:
      type: object
      properties:
        stopwords:
          type: array
          items:
            type: string
        locale:
          type: string
      required:
        - stopwords
      example: |
        {"stopwords": ["Germany", "France", "Italy"], "locale": "en"}
    StopwordsSetSchema:
      type: object
      properties:
        id:
          type: string
        stopwords:
          type: array
          items:
            type: string
        locale:
          type: string
      required:
        - id
        - stopwords
      example: |
        {"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}
    StopwordsSetRetrieveSchema:
      type: object
      properties:
        stopwords:
          $ref: "#/components/schemas/StopwordsSetSchema"
      required:
        - stopwords
      example: |
        {"stopwords": {"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}}
    StopwordsSetsRetrieveAllSchema:
      type: object
      properties:
        stopwords:
          type: array
          items:
            $ref: "#/components/schemas/StopwordsSetSchema"
      required:
        - stopwords
      example: |
        {"stopwords": [{"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}]}
    PresetUpsertSchema:
      properties:
        value:
          oneOf:
            - $ref: '#/components/schemas/SearchParameters'
            - $ref: '#/components/schemas/MultiSearchSearchesParameter'
      required:
        - value
    PresetSchema:
      allOf:
        - $ref: '#/components/schemas/PresetUpsertSchema'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
    PresetsRetrieveSchema:
      type: object
      required:
        - presets
      properties:
        presets:
          type: array
          items:
            $ref: '#/components/schemas/PresetSchema'
          x-go-type: '[]*PresetSchema'
    PresetDeleteSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    # client libraries already have .create, .upsert,... methods so we omit the `action` param
    DocumentIndexParameters:
      type: object
      properties:
        dirty_values:
          $ref: "#/components/schemas/DirtyValues"
    DirtyValues:
      type: string
      enum: [coerce_or_reject, coerce_or_drop, drop, reject]
    IndexAction:
      type: string
      enum: [create, update, upsert, emplace]
    DropTokensMode:
      type: string
      enum: [right_to_left, left_to_right, both_sides:3]
      description: >
        Dictates the direction in which the words in the query must be dropped when the original words in the query do not appear in any document.
        Values: right_to_left (default), left_to_right, both_sides:3
        A note on both_sides:3 - for queries upto 3 tokens (words) in length, this mode will drop tokens from both sides and exhaustively rank all matching results.
        If query length is greater than 3 words, Typesense will just fallback to default behavior of right_to_left
    ConversationModelCreateSchema:
      required:
        - model_name
        - max_bytes
      allOf:
        - $ref: '#/components/schemas/ConversationModelUpdateSchema'
        - type: object
          required:
            - model_name
            - max_bytes
            - history_collection
          properties:
            model_name:
              description: Name of the LLM model offered by OpenAI, Cloudflare or vLLM
              type: string
            max_bytes:
              description: |
                The maximum number of bytes to send to the LLM in every API call. Consult the LLM's documentation on the number of bytes supported in the context window.
              type: integer
            history_collection:
              type: string
              description: Typesense collection that stores the historical conversations
    ConversationModelUpdateSchema:
      type: object
      properties:
        id:
          type: string
          description: An explicit id for the model, otherwise the API will return a response with an auto-generated conversation model id.
        model_name:
          description: Name of the LLM model offered by OpenAI, Cloudflare or vLLM
          type: string
        api_key:
          description: The LLM service's API Key
          type: string
        history_collection:
          type: string
          description: Typesense collection that stores the historical conversations
        account_id:
          description: LLM service's account ID (only applicable for Cloudflare)
          type: string
        system_prompt:
          description: The system prompt that contains special instructions to the LLM
          type: string
        ttl:
          type: integer
          description: |
            Time interval in seconds after which the messages would be deleted. Default: 86400 (24 hours)
        max_bytes:
          description: |
            The maximum number of bytes to send to the LLM in every API call. Consult the LLM's documentation on the number of bytes supported in the context window.
          type: integer
        vllm_url:
          description: URL of vLLM service
          type: string
    ConversationModelSchema:
      allOf:
        - $ref: '#/components/schemas/ConversationModelCreateSchema'
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: An explicit id for the model, otherwise the API will return a response with an auto-generated conversation model id.
    StemmingDictionary:
      type: object
      required:
        - id
        - words
      properties:
        id:
          type: string
          description: Unique identifier for the dictionary
          example: irregular-plurals
        words:
          type: array
          description: List of word mappings in the dictionary
          items:
            type: object
            required:
              - word
              - root
            properties:
              word:
                type: string
                description: The word form to be stemmed
                example: people
              root:
                type: string
                description: The root form of the word
                example: person
  securitySchemes:
    api_key_header:
      type: apiKey
      name: X-TYPESENSE-API-KEY
      in: header