openapi.yml

openapi: 3.0.3
info:
  title: Typesense API
  description: "An open source search engine for building delightful search experiences."
  version: '30.0'
  license:
    name: GPL-3.0
    url: https://opensource.org/licenses/GPL-3.0
servers:
  - url: "{protocol}://{hostname}:{port}"
    description: Typesense Server
    variables:
      protocol:
        default: http
        description: The protocol of your Typesense server
      hostname:
        default: localhost
        description: The hostname of your Typesense server
      port:
        default: "8108"
        description: The port of your Typesense server
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: 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: curation_sets
    description: Manage curation sets
  - name: stemming
    description: Manage stemming dictionaries
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/28.0/api/stemming.html
  - name: nl_search_models
    description: Manage NL search models
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/29.0/api/natural-language-search.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
      parameters:
        - name: getCollectionsParameters
          in: query
          schema:
            type: object
            properties:
              exclude_fields:
                description: Comma-separated list of fields from the collection to exclude from the response
                type: string
              limit:
                description: >
                  Number of collections to fetch.
                  Default: returns all collections.
                type: integer
              offset:
                description: Identifies the starting point to return collections when paginating.
                type: integer
      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"

  /synonym_sets:
    get:
      tags:
        - synonyms
      summary: List all synonym sets
      description: Retrieve all synonym sets
      operationId: retrieveSynonymSets
      responses:
        "200":
          description: List of all synonym sets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SynonymSetSchema"

  /synonym_sets/{synonymSetName}:
    get:
      tags:
        - synonyms
      summary: Retrieve a synonym set
      description: Retrieve a specific synonym set by its name
      operationId: retrieveSynonymSet
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Synonym set fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymSetSchema"
        "404":
          description: Synonym set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      tags:
        - synonyms
      summary: Create or update a synonym set
      description: Create or update a synonym set with the given name
      operationId: upsertSynonymSet
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The synonym set to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SynonymSetCreateSchema"
        required: true
      responses:
        "200":
          description: Synonym set successfully created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymSetSchema"
        "400":
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - synonyms
      summary: Delete a synonym set
      description: Delete a specific synonym set by its name
      operationId: deleteSynonymSet
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Synonym set successfully deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymSetDeleteSchema"
        "404":
          description: Synonym set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /synonym_sets/{synonymSetName}/items:
    get:
      tags:
        - synonyms
      summary: List items in a synonym set
      description: Retrieve all synonym items in a set
      operationId: retrieveSynonymSetItems
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set to retrieve items for
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of synonym items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SynonymItemSchema"
        "404":
          description: Synonym set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /synonym_sets/{synonymSetName}/items/{itemId}:
    get:
      tags:
        - synonyms
      summary: Retrieve a synonym set item
      description: Retrieve a specific synonym item by its id
      operationId: retrieveSynonymSetItem
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the synonym item to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Synonym item fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymItemSchema"
        "404":
          description: Synonym item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    put:
      tags:
        - synonyms
      summary: Create or update a synonym set item
      description: Create or update a synonym set item with the given id
      operationId: upsertSynonymSetItem
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the synonym item to upsert
          required: true
          schema:
            type: string
      requestBody:
        description: The synonym item to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SynonymItemUpsertSchema"
        required: true
      responses:
        "200":
          description: Synonym item successfully created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymItemSchema"
        "400":
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - synonyms
      summary: Delete a synonym set item
      description: Delete a specific synonym item by its id
      operationId: deleteSynonymSetItem
      parameters:
        - name: synonymSetName
          in: path
          description: The name of the synonym set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the synonym item to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Synonym item successfully deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SynonymItemDeleteSchema"
        "404":
          description: Synonym item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /curation_sets:
    get:
      tags:
        - curation_sets
      summary: List all curation sets
      description: Retrieve all curation sets
      operationId: retrieveCurationSets
      responses:
        "200":
          description: List of all curation sets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CurationSetSchema"

  /curation_sets/{curationSetName}:
    get:
      tags:
        - curation_sets
      summary: Retrieve a curation set
      description: Retrieve a specific curation set by its name
      operationId: retrieveCurationSet
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Curation set fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationSetSchema"
        "404":
          description: Curation set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    put:
      tags:
        - curation_sets
      summary: Create or update a curation set
      description: Create or update a curation set with the given name
      operationId: upsertCurationSet
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The curation set to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CurationSetCreateSchema"
        required: true
      responses:
        "200":
          description: Curation set successfully created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationSetSchema"
        "400":
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - curation_sets
      summary: Delete a curation set
      description: Delete a specific curation set by its name
      operationId: deleteCurationSet
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Curation set successfully deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationSetDeleteSchema"
        "404":
          description: Curation set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /curation_sets/{curationSetName}/items:
    get:
      tags:
        - curation_sets
      summary: List items in a curation set
      description: Retrieve all curation items in a set
      operationId: retrieveCurationSetItems
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set to retrieve items for
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of curation items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CurationItemSchema"
        "404":
          description: Curation set not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /curation_sets/{curationSetName}/items/{itemId}:
    get:
      tags:
        - curation_sets
      summary: Retrieve a curation set item
      description: Retrieve a specific curation item by its id
      operationId: retrieveCurationSetItem
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the curation item to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Curation item fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationItemSchema"
        "404":
          description: Curation item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    put:
      tags:
        - curation_sets
      summary: Create or update a curation set item
      description: Create or update a curation set item with the given id
      operationId: upsertCurationSetItem
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the curation item to upsert
          required: true
          schema:
            type: string
      requestBody:
        description: The curation item to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CurationItemCreateSchema"
        required: true
      responses:
        "200":
          description: Curation item successfully created/updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationItemSchema"
        "400":
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - curation_sets
      summary: Delete a curation set item
      description: Delete a specific curation item by its id
      operationId: deleteCurationSetItem
      parameters:
        - name: curationSetName
          in: path
          description: The name of the curation set
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The id of the curation item to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Curation item successfully deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurationItemDeleteSchema"
        "404":
          description: Curation item 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: Retrieve 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:
      summary: Create a conversation model
      description: Create a Conversation Model
      operationId: createConversationModel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationModelCreateSchema'
        required: true
      responses:
        '201':
          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"
  /operations/cache/clear:
    post:
      tags:
        - operations
      summary: Clear the cached responses of search requests in the LRU cache.
      description:
        Clear the cached responses of search requests that are sent with `use_cache` parameter in the LRU cache.
      operationId: clearCache
      responses:
        '200':
          description: Clear cache succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /operations/db/compact:
    post:
      tags:
        - operations
      summary: Compacting the on-disk database
      description:
        Typesense uses RocksDB to store your documents on the disk. If you do frequent writes or updates, you could benefit from running a compaction of the underlying RocksDB database.
        This could reduce the size of the database and decrease read latency. While the database will not block during this operation, we recommend running it during off-peak hours.
      operationId: compactDb
      responses:
        '200':
          description: Compacting the on-disk database succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /config:
    post:
      tags:
        - operations
      summary: Toggle Slow Request Log
      description:
        Enable logging of requests that take over a defined threshold of time.
        Default is `-1` which disables slow request logging.
        Slow requests are logged to the primary log file, with the prefix SLOW REQUEST.
      operationId: toggleSlowRequestLog
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                log-slow-requests-time-ms:
                  type: integer
              required:
                - log-slow-requests-time-ms
              example: |
                {"log-slow-requests-time-ms": 2000}
      responses:
        '200':
          description: Toggle Slow Request Log database succeeded.
          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: Submit a single analytics event. The event must correspond to an existing analytics rule by name.
      operationId: createAnalyticsEvent
      requestBody:
        description: The analytics event to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsEvent'
        required: true
      responses:
        '200':
          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'
    get:
      tags:
        - analytics
      summary: Retrieve analytics events
      description: Retrieve the most recent events for a user and rule.
      operationId: getAnalyticsEvents
      parameters:
        - name: user_id
          in: query
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: Analytics rule name
          required: true
          schema:
            type: string
        - name: n
          in: query
          description: Number of events to return (max 1000)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Events fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsEventsResponse'
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /analytics/flush:
    post:
      tags:
        - analytics
      summary: Flush in-memory analytics to disk
      description: Triggers a flush of analytics data to persistent storage.
      operationId: flushAnalytics
      responses:
        '200':
          description: Flush triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsEventCreateResponse'
  /analytics/status:
    get:
      tags:
        - analytics
      summary: Get analytics subsystem status
      description: Returns sizes of internal analytics buffers and queues.
      operationId: getAnalyticsStatus
      responses:
        '200':
          description: Status fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsStatus'
  /analytics/rules:
    post:
      tags:
        - analytics
      summary: Create analytics rule(s)
      description: Create one or more analytics rules. You can send a single rule object or an array of rule objects.
      operationId: createAnalyticsRule
      requestBody:
        description: The analytics rule(s) to be created
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AnalyticsRuleCreate"
                - type: array
                  items:
                    $ref: "#/components/schemas/AnalyticsRuleCreate"
        required: true
      responses:
        '200':
          description: Analytics rule(s) successfully created
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/AnalyticsRule"
                  - type: array
                    items:
                      oneOf:
                        - $ref: "#/components/schemas/AnalyticsRule"
                        - type: object
                          properties:
                            error:
                              type: string
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    get:
      tags:
        - analytics
      summary: Retrieve analytics rules
      description: Retrieve all analytics rules. Use the optional rule_tag filter to narrow down results.
      operationId: retrieveAnalyticsRules
      parameters:
        - in: query
          name: rule_tag
          schema:
            type: string
          required: false
          description: Filter rules by rule_tag
      responses:
        '200':
          description: Analytics rules fetched
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AnalyticsRule"
  /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/AnalyticsRuleUpdate"
        required: true
      responses:
        '200':
          description: Analytics rule successfully upserted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsRule"
        '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/AnalyticsRule"
        '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/AnalyticsRule"
        '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"
  /nl_search_models:
    get:
      tags:
        - nl_search_models
      summary: List all NL search models
      description: Retrieve all NL search models.
      operationId: retrieveAllNLSearchModels
      responses:
        '200':
          description: List of all NL search models
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NLSearchModelSchema'
    post:
      tags:
        - nl_search_models
      summary: Create a NL search model
      description: Create a new NL search model.
      operationId: createNLSearchModel
      requestBody:
        description: The NL search model to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLSearchModelCreateSchema'
        required: true
      responses:
        '201':
          description: NL search model successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModelSchema'
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /nl_search_models/{modelId}:
    get:
      tags:
        - nl_search_models
      summary: Retrieve a NL search model
      description: Retrieve a specific NL search model by its ID.
      operationId: retrieveNLSearchModel
      parameters:
        - name: modelId
          in: path
          description: The ID of the NL search model to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: NL search model fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModelSchema'
        '404':
          description: NL search model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    put:
      tags:
        - nl_search_models
      summary: Update a NL search model
      description: Update an existing NL search model.
      operationId: updateNLSearchModel
      parameters:
        - name: modelId
          in: path
          description: The ID of the NL search model to update
          required: true
          schema:
            type: string
      requestBody:
        description: The NL search model fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLSearchModelUpdateSchema'
        required: true
      responses:
        '200':
          description: NL search model successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModelSchema'
        '400':
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: NL search model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    delete:
      tags:
        - nl_search_models
      summary: Delete a NL search model
      description: Delete a specific NL search model by its ID.
      operationId: deleteNLSearchModel
      parameters:
        - name: modelId
          in: path
          description: The ID of the NL search model to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: NL search model successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLSearchModelDeleteSchema'
        '404':
          description: NL search model not found
          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: []
        synonym_sets:
          type: array
          description: List of synonym set names to associate with this collection
          items:
            type: string
            example: "synonym_set_1"
        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"
        metadata:
          type: object
          description: >
            Optional details about the collection, e.g., when it was created, who created it etc.
    CollectionUpdateSchema:
      type: object
      minProperties: 1
      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"
        synonym_sets:
          type: array
          description: List of synonym set names to associate with this collection
          items:
            type: string
            example: "synonym_set_1"
        metadata:
          type: object
          description: >
            Optional details about the collection, e.g., when it was created, who created it etc.
    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.
        async_reference:
          type: boolean
          description: >
            Allow documents to be indexed successfully even when the referenced document doesn't exist yet.
        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:
          $ref: "#/components/schemas/SearchRequestParams"
        conversation:
          $ref: "#/components/schemas/SearchResultConversation"
        union_request_params:
          type: array
          description: Returned only for union query response.
          items:
            $ref: "#/components/schemas/SearchRequestParams"
        metadata:
          type: object
          description: Custom JSON object that can be returned in the search response
          additionalProperties: true
    SearchRequestParams:
      type: object
      required:
        - collection_name
        - q
        - per_page
      properties:
        collection_name:
          type: string
        first_q:
          type: string
        q:
          type: string
        per_page:
          type: integer
        voice_query:
          type: object
          properties:
            transcribed_query:
              type: string
    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
              format: int64
              x-go-type: uint64
            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
        hybrid_search_info:
          type: object
          description: Information about hybrid search scoring
          properties:
            rank_fusion_score:
              type: number
              format: float
              description: Combined score from rank fusion of text and vector search
        search_index:
          type: integer
          description: Returned only for union query response. Indicates the index of the query which this document matched to.
      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{}"
    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"
    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

        validate_field_names:
          description: >
            Controls whether Typesense should validate if the fields exist in the schema.
            When set to false, Typesense will not throw an error if a field is missing.
            This is useful for programmatic grouping where not all fields may exist.
          type: boolean

        nl_query:
          description: Whether to use natural language processing to parse the query.
          type: boolean

        nl_model_id:
          description: The ID of the natural language model to use.
          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 your open 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

        enable_analytics:
          description: >
            Flag for enabling/disabling analytics aggregation for specific search
            queries (for e.g. those originating from a test script).
          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

        synonym_sets:
          type: string
          description: List of synonym set names to associate with this search query
          example: "synonym_set_1,synonym_set_2"

        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 (curation 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 Curation feature to override search results based
            on rules. Curations 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 Curation feature to override search results based
            on rules. Curations are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        curation_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_curations:
          description: >
            If you have some curation sets 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 (curation 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

        enable_analytics:
          description: >
            Flag for enabling/disabling analytics aggregation for specific search
            queries (for e.g. those originating from a test script).
          type: boolean
          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 Curation feature to override search results based
            on rules. Curations 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 Curation feature to override search results based
            on rules. Curations are applied first, followed by `pinned_hits` and
            finally `hidden_hits`.
          type: string

        curation_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_curations:
          description: >
            If you have some curation sets 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
        validate_field_names:
          description: >
            Controls whether Typesense should validate if the fields exist in the schema.
            When set to false, Typesense will not throw an error if a field is missing.
            This is useful for programmatic grouping where not all fields may exist.
          type: boolean

    MultiSearchSearchesParameter:
      type: object
      required:
        - searches
      properties:
        union:
          type: boolean
          default: false
          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
        sampled:
          type: boolean
        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
    AnalyticsEvent:
      type: object
      required:
        - name
        - event_type
        - data
      properties:
        name:
          type: string
          description: Name of the analytics rule this event corresponds to
        event_type:
          type: string
          description: Type of event (e.g., click, conversion, query, visit)
        data:
          type: object
          description: Event payload
          properties:
            user_id:
              type: string
            doc_id:
              type: string
            doc_ids:
              type: array
              items:
                type: string
            q:
              type: string
            analytics_tag:
              type: string
    AnalyticsEventsResponse:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              event_type: { type: string }
              collection: { type: string }
              timestamp: { type: integer, format: int64 }
              user_id: { type: string }
              doc_id: { type: string }
              doc_ids:
                type: array
                items: { type: string }
              query: { type: string }
    AnalyticsRuleCreate:
      type: object
      required:
        - name
        - type
        - collection
        - event_type
      properties:
        name:
          type: string
        type:
          $ref: "#/components/schemas/AnalyticsRuleType"
        collection:
          type: string
        event_type:
          type: string
        rule_tag:
          type: string
        params:
          type: object
          properties:
            destination_collection:
              type: string
            limit:
              type: integer
            capture_search_requests:
              type: boolean
            meta_fields:
              type: array
              items: { type: string }
            expand_query:
              type: boolean
            counter_field:
              type: string
            weight:
              type: integer
    AnalyticsRuleType:
      type: string
      enum: [popular_queries, nohits_queries, counter, log]
    AnalyticsRuleUpdate:
      type: object
      description: Fields allowed to update on an analytics rule
      properties:
        name:
          type: string
        rule_tag:
          type: string
        params:
          type: object
          properties:
            destination_collection:
              type: string
            limit:
              type: integer
            capture_search_requests:
              type: boolean
            meta_fields:
              type: array
              items: { type: string }
            expand_query:
              type: boolean
            counter_field:
              type: string
            weight:
              type: integer
    AnalyticsRule:
      allOf:
        - $ref: '#/components/schemas/AnalyticsRuleCreate'
        - type: object
    AnalyticsStatus:
      type: object
      properties:
        popular_prefix_queries: { type: integer }
        nohits_prefix_queries: { type: integer }
        log_prefix_queries: { type: integer }
        query_log_events: { type: integer }
        query_counter_events: { type: integer }
        doc_log_events: { type: integer }
        doc_counter_events: { type: integer }

    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
    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 up to 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
    NLSearchModelBase:
      type: object
      properties:
        model_name:
          type: string
          description: Name of the NL model to use
        api_key:
          type: string
          description: API key for the NL model service
        api_url:
          type: string
          description: Custom API URL for the NL model service
        max_bytes:
          type: integer
          description: Maximum number of bytes to process
        temperature:
          type: number
          description: Temperature parameter for the NL model
        system_prompt:
          type: string
          description: System prompt for the NL model
        top_p:
          type: number
          description: Top-p parameter for the NL model (Google-specific)
        top_k:
          type: integer
          description: Top-k parameter for the NL model (Google-specific)
        stop_sequences:
          type: array
          items:
            type: string
          description: Stop sequences for the NL model (Google-specific)
        api_version:
          type: string
          description: API version for the NL model service
        project_id:
          type: string
          description: Project ID for GCP Vertex AI
        access_token:
          type: string
          description: Access token for GCP Vertex AI
        refresh_token:
          type: string
          description: Refresh token for GCP Vertex AI
        client_id:
          type: string
          description: Client ID for GCP Vertex AI
        client_secret:
          type: string
          description: Client secret for GCP Vertex AI
        region:
          type: string
          description: Region for GCP Vertex AI
        max_output_tokens:
          type: integer
          description: Maximum output tokens for GCP Vertex AI
        account_id:
          type: string
          description: Account ID for Cloudflare-specific models

    NLSearchModelCreateSchema:
      allOf:
        - $ref: '#/components/schemas/NLSearchModelBase'
        - type: object
          properties:
            id:
              type: string
              description: Optional ID for the NL search model

    NLSearchModelSchema:
      allOf:
        - $ref: '#/components/schemas/NLSearchModelCreateSchema'
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: ID of the NL search model

    NLSearchModelUpdateSchema:
      $ref: '#/components/schemas/NLSearchModelCreateSchema'

    NLSearchModelDeleteSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the deleted NL search model

    SynonymItemUpsertSchema:
      type: object
      required:
        - synonyms
      properties:
        synonyms:
          type: array
          description: Array of words that should be considered as synonyms
          items:
            type: string
        root:
          type: string
          description: For 1-way synonyms, indicates the root word that words in the synonyms parameter map to
        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

    SynonymItemSchema:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Unique identifier for the synonym item
        - $ref: "#/components/schemas/SynonymItemUpsertSchema"

    SynonymSetCreateSchema:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          description: Array of synonym items
          items:
            $ref: "#/components/schemas/SynonymItemSchema"

    SynonymSetSchema:
      allOf:
        - $ref: "#/components/schemas/SynonymSetCreateSchema"
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the synonym set

    SynonymSetsRetrieveSchema:
      type: object
      required:
        - synonym_sets
      properties:
        synonym_sets:
          type: array
          description: Array of synonym sets
          items:
            $ref: "#/components/schemas/SynonymSetSchema"

    SynonymSetDeleteSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the deleted synonym set

    SynonymItemDeleteSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the deleted synonym item

    CurationItemCreateSchema:
      type: object
      required:
        - rule
      properties:
        rule:
          $ref: '#/components/schemas/CurationRule'
        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/CurationInclude'
        excludes:
          type: array
          description: List of document `id`s that should be excluded from the search results.
          items:
            $ref: '#/components/schemas/CurationExclude'
        filter_by:
          type: string
          description: >
            A filter by clause that is applied to any search query that matches the curation rule.
        remove_matched_tokens:
          type: boolean
          description: >
            Indicates whether search query tokens that exist in the curation'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 curation rule.
        replace_query:
          type: string
          description: >
            Replaces the current search query with this value, when the search query matches the curation 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 curation will be active. You can use this to create 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 curation will be active. You can use this to create rules that stop applying after a period of time.
        stop_processing:
          type: boolean
          description: >
            When set to true, curation processing will stop at the first matching rule. When set to false curation processing will continue and multiple curation actions will be triggered in sequence.
            Curations are processed in the lexical sort order of their id field.
        id:
          type: string
          description: ID of the curation item


    CurationItemSchema:
      allOf:
        - $ref: '#/components/schemas/CurationItemCreateSchema'
        - type: object
          required:
            - id
          properties:
            id:
              type: string

    CurationSetCreateSchema:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          description: Array of curation items
          items:
            $ref: '#/components/schemas/CurationItemCreateSchema'
        description:
          type: string
          description: Optional description for the curation set

    CurationSetSchema:
      allOf:
        - $ref: '#/components/schemas/CurationSetCreateSchema'
        - type: object
          required:
            - name
          properties:
            name:
              type: string

    CurationRule:
      type: object
      properties:
        tags:
          type: array
          description: List of tag values to associate with this curation rule.
          items:
            type: string
        query:
          type: string
          description: Indicates what search queries should be curated
        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 curation should apply when the filter_by parameter in a search query exactly matches the string specified here (including backticks, spaces, brackets, etc).

    CurationInclude:
      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

    CurationExclude:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: document id that should be excluded from the search results.

    CurationSetDeleteSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the deleted curation set
    CurationItemDeleteSchema:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the deleted curation item

  securitySchemes:
    api_key_header:
      type: apiKey
      name: X-TYPESENSE-API-KEY
      in: header