openapi.yaml

openapi: 3.0.3
info:
  title: Typesense API
  description: "An open source search engine for building delightful search experiences."
  version: 0.23.0
externalDocs:
  description: Find out more about Typsesense
  url: https://typesense.org
security:
  - api_key_header: []
tags:
  - name: collections
    description: A collection is defined by a schema
    externalDocs:
      description: Find out more
      url: https://typesense.org/api/#create-collection
  - name: documents
    description: A document is an individual record to be indexed and belongs to a collection
    externalDocs:
      description: Find out more
      url: https://typesense.org/api/#index-document
  - name: promote
    description: Promote certain documents over others
    externalDocs:
      description: Find out more
      url: https://typesense.org/docs/0.23.0/api/#curation
  - 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/0.23.0/api/#cluster-operations

paths:
  /collections:
    get:
      tags:
        - collections
      summary: List all collections
      description:
        Returns a summary of all your collections. The collections are
        returned sorted by creation date, with the most recent collections appearing
        first.
      operationId: getCollections
      responses:
        200:
          description: List of all collections
          content:
            application/json:
              schema:
                type: array
                x-go-type: "[]*CollectionResponse"
                items:
                  $ref: "#/components/schemas/CollectionResponse"
    post:
      tags:
        - collections
      summary: Create a new collection
      description:
        When a collection is created, we give it a name and describe the
        fields that will be indexed from the documents added to the collection.
      operationId: createCollection
      requestBody:
        description: The collection object to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionSchema"
        required: true
      responses:
        201:
          description: Collection successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        400:
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        409:
          description: Collection already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}:
    get:
      tags:
        - collections
      summary: Retrieve a single collection
      description: Retrieve the details of a collection, given its name.
      operationId: getCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to retrieve
          required: true
          schema:
            type: string
      responses:
        200:
          description: Collection fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        404:
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    patch:
      tags:
        - collections
      summary: Update a collection
      description:
        Update a collection's schema to modify the fields and their types.
      operationId: updateCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to update
          required: true
          schema:
            type: string
      requestBody:
        description: The document object with fields to be updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectionUpdateSchema"
        required: true
      responses:
        200:
          description: The updated partial collection schema
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionUpdateSchema"
        400:
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        404:
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - collections
      summary: Delete a collection
      description:
        Permanently drops a collection. This action cannot be undone. For
        large collections, this might have an impact on read latencies.
      operationId: deleteCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to delete
          required: true
          schema:
            type: string
      responses:
        200:
          description: Collection deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponse"
        404:
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents:
    post:
      tags:
        - documents
      summary: Index a document
      description:
        A document to be indexed in a given collection must conform to
        the schema of the collection.
      operationId: indexDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to add the document to
          required: true
          schema:
            type: string
        - name: action
          in: query
          description: Additional action to perform
          schema:
            type: string
            example: upsert
            enum:
              - upsert
      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"
    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
            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
      responses:
        200:
          description: Documents successfully deleted
          content:
            application/json:
              schema:
                type: object
                required:
                  - num_deleted
                properties:
                  num_deleted:
                    type: integer
        404:
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents/search:
    get:
      tags:
        - documents
      summary: Search for documents in a collection
      description: Search for documents in a collection that match the search criteria.
      operationId: searchCollection
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: searchParameters
          required: true
          in: query
          schema:
            $ref: "#/components/schemas/SearchParameters"
      responses:
        200:
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        400:
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        404:
          description: The collection or field was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/overrides:
    get:
      tags:
        - documents
        - promote
      summary: List all collection overrides
      operationId: getSearchOverrides
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
      responses:
        200:
          description: List of all search overrides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverridesResponse"
  /collections/{collectionName}/overrides/{overrideId}:
    get:
      tags:
        - documents
        - override
      summary: Retrieve a single search override
      description: Retrieve the details of a search override, given its id.
      operationId: getSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The id of the search override
          required: true
          schema:
            type: string
      responses:
        200:
          description: Search override fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverride"
    put:
      tags:
        - documents
        - promote
      summary: Create or update an override to promote certain documents over others
      description:
        Create or update an override to promote certain documents over others.
        Using overrides, you can include or exclude specific documents for a given query.
      operationId: upsertSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The ID of the search override to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The search override object to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchOverrideSchema"
        required: true
      responses:
        200:
          description: Created/updated search override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverride"
        404:
          description: Search override not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - documents
        - promote
      summary: Delete an override associated with a collection
      operationId: deleteSearchOverride
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: overrideId
          in: path
          description: The ID of the search override to delete
          required: true
          schema:
            type: string
      responses:
        200:
          description: The ID of the deleted search override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchOverride"
        404:
          description: Search override not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/synonyms:
    get:
      tags:
        - documents
      summary: List all collection synonyms
      operationId: getSearchSynonyms
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
      responses:
        200:
          description: List of all search synonyms
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonymsResponse"
        404:
          description: Search synonyms was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/synonyms/{synonymId}:
    get:
      tags:
        - documents
      summary: Retrieve a single search synonym
      description: Retrieve the details of a search synonym, given its id.
      operationId: getSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The id of the search synonym
          required: true
          schema:
            type: string
      responses:
        200:
          description: Search synonym fetched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonym"
        404:
          description: Search synonym was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    put:
      tags:
        - documents
      summary: Create or update a synonym
      description: Create or update a synonym  to define search terms that should be considered equivalent.
      operationId: upsertSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The ID of the search synonym to create/update
          required: true
          schema:
            type: string
      requestBody:
        description: The search synonym object to be created/updated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchSynonymSchema"
        required: true
      responses:
        200:
          description: Created/updated search synonym
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonym"
        404:
          description: Search synonym was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    delete:
      tags:
        - documents
      summary: Delete a synonym associated with a collection
      operationId: deleteSearchSynonym
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: synonymId
          in: path
          description: The ID of the search synonym to delete
          required: true
          schema:
            type: string
      responses:
        200:
          description: The ID of the deleted search synonym
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSynonym"
        404:
          description: Search synonym not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /collections/{collectionName}/documents/export:
    get:
      tags:
        - documents
      summary: Export all documents in a collection
      description: Export all documents in a collection in JSON lines format.
      operationId: exportDocuments
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection
          required: true
          schema:
            type: string
        - name: exportDocumentsParameters
          in: query
          schema:
            type: object
            required:
              - include_fields
              - exclude_fields
            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
        - name: importDocumentsParameters
          in: query
          schema:
            type: object
            properties:
              action:
                type: string
              batch_size:
                type: integer
              dirty_values:
                type: string
                enum:
                  - coerce_or_reject
                  - coerce_or_drop
                  - drop
                  - reject
      requestBody:
        description: The json array of documents or the JSONL file to import
        content:
          application/octet-stream:
            schema:
              type: string
              description: The JSONL file to import
        required: true
      responses:
        200:
          description:
            Result of the import operation. Each line of the response indicates the result
            of each document present in the request body (in the same order). If the import
            of a single document fails, it does not affect the other documents.
            If there is a failure, the response line will include a corresponding error
            message and as well as the actual document content.
          content:
            application/octet-stream:
              schema:
                type: string
                example: |
                  {"success": true}
                  {"success": false, "error": "Bad JSON.", "document": "[bad doc"}
        400:
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        404:
          description: The collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
  /collections/{collectionName}/documents/{documentId}:
    get:
      tags:
        - documents
      summary: Retreive a document
      description: Fetch an individual document from a collection by using its ID.
      operationId: getDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          description: The Document ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: The document referenced by the ID
          content:
            application/json:
              schema:
                type: object
                description: Can be any key-value pair
        404:
          description: The document or collection was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
    patch:
      tags:
        - documents
      summary: Update a document
      description:
        Update an individual document from a collection by using its ID.
        The update can be partial.
      operationId: updateDocument
      parameters:
        - name: collectionName
          in: path
          description: The name of the collection to search for the document under
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          description: The Document ID
          required: true
          schema:
            type: string
      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"
  /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/ApiKey"
        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/snapshot:
    post:
      tags:
        - operations
      summary: Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
      description:
        Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
        You can then backup the snapshot directory that gets created and later restore it
        as a data directory, as needed.
      operationId: takeSnapshot
      parameters:
        - name: snapshot_path
          in: query
          description: The directory on the server where the snapshot should be saved.
          required: true
          schema:
            type: string
      responses:
        201:
          description: Snapshot is created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /operations/vote:
    post:
      tags:
        - operations
      summary: Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
      description:
        Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
        The follower node that you run this operation against will become the new leader,
        once this command succeeds.
      operationId: vote
      responses:
        200:
          description: Re-election is performed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessStatus"
  /multi_search:
    post:
      operationId: multiSearch
      tags:
        - documents
      summary: send multiple search requests in a single HTTP request
      description:
        This is especially useful to avoid round-trip network latencies incurred otherwise if each of these requests are sent in separate HTTP requests.
        You can also use this feature to do a federated search across multiple collections in a single HTTP request.
      parameters:
        - name: multiSearchParameters
          required: true
          in: query
          schema:
            $ref: "#/components/schemas/MultiSearchParameters"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultiSearchSearchesParameter"
      responses:
        200:
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiSearchResult"
        400:
          description: Bad request, see error message for details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

components:
  schemas:
    CollectionSchema:
      required:
        - name
        - fields
      type: object
      properties:
        name:
          type: string
          description: Name of the collection
          example: companies
        fields:
          type: array
          description: A list of fields for querying, filtering and faceting
          example:
            - name: num_employees
              type: int32
              facet: false
            - name: company_name
              type: string
              facet: false
            - name: country
              type: string
              facet: true
          items:
            $ref: "#/components/schemas/Field"
        default_sorting_field:
          type: string
          description:
            The name of an int32 / float field that determines the order in which
            the search results are ranked when a sort_by clause is not provided during
            searching. This field must indicate some kind of popularity.
          example: num_employees # Go with the first field name listed above to produce sane defaults
          default: ""
        token_separators:
          type: array
          description: >
            List of symbols or special characters to be used for 
            splitting the text into individual words in addition to space and new-line characters.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
        enable_nested_fields:
          type: boolean
          description:
            Enables experimental support at a collection level for nested object or object array fields.
            This field is only available if the Typesense server is version `0.24.0.rcn34` or later.
          default: false
          example: true
        symbols_to_index:
          type: array
          description: >
            List of symbols or special characters to be indexed.
          items:
            type: string # characters only
            # Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
            # enum: ["@", "!", ".", "/", ","]
            minLength: 1
            maxLength: 1
          default: []
    CollectionUpdateSchema:
      required:
        - fields
      type: object
      properties:
        fields:
          type: array
          description: A list of fields for querying, filtering and faceting
          example:
            - name: company_name
              type: string
              facet: false
            - name: num_employees
              type: int32
              facet: false
            - name: country
              type: string
              facet: true
          items:
            $ref: "#/components/schemas/Field"
    CollectionResponse:
      allOf:
        - $ref: "#/components/schemas/CollectionSchema"
        - type: object
          required:
            - num_documents
            - created_at
          properties:
            num_documents:
              type: integer
              description: Number of documents in the collection
              format: int64
              readOnly: true
            created_at:
              type: integer
              description: Timestamp of when the collection was created
              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
          default: false
        facet:
          type: boolean
          example: false
          default: false
        index:
          type: boolean
          example: true
          default: true
        locale:
          type: string
          example: el
        sort:
          type: boolean
          example: true
          default: false
        infix:
          type: boolean
          example: true
          default: false
        drop:
          type: boolean
          example: true
          # omitting default value since we want it to be null
    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
        search_time_ms:
          type: integer
          description: The number of milliseconds the search took
        out_of:
          type: integer
          description: The total number of pages
        search_cutoff:
          type: boolean
          description: Whether the search was cut off
        page:
          type: integer
          description: The search result page number
        grouped_hits:
          type: array
          items:
            $ref: "#/components/schemas/SearchGroupedHit"
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
        request_params:
          type: object
          required:
            - collection_name
            - q
            - per_page
          properties:
            collection_name:
              type: string
            q:
              type: string
            per_page:
              type: integer

    SearchGroupedHit:
      type: object
      required:
        - group_key
        - hits
      properties:
        group_key:
          type: array
          items:
            type: string
        hits:
          type: array
          description: The documents that matched the search query
          items:
            $ref: "#/components/schemas/SearchResultHit"
    SearchResultHit:
      type: object
      properties:
        highlights:
          type: array
          description: Contains highlighted portions of the search fields
          items:
            $ref: "#/components/schemas/SearchHighlight"
        document:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: object
        text_match:
          type: integer
          format: int64
        geo_distance_meters:
          type: object
          description: Can be any key-value pair
          additionalProperties:
            type: integer
      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
        indices:
          type: array
          description: The indices property will be present only for string[]
            fields and will contain the corresponding indices of the snippets
            in the search field
          example: 1
          items:
            type: integer
        matched_tokens:
          type: array
          items:
            type: object
            x-go-type: "interface{}"
    SearchOverrideSchema:
      type: object
      required:
        - rule
      properties:
        rule:
          $ref: "#/components/schemas/SearchOverrideRule"
        includes:
          type: array
          description:
            List of document `id`s that should be included in the search results with their
            corresponding `position`s.
          items:
            $ref: "#/components/schemas/SearchOverrideInclude"
        excludes:
          type: array
          description: List of document `id`s that should be excluded from the search results.
          items:
            $ref: "#/components/schemas/SearchOverrideExclude"
        filter_by:
          type: string
          description: >
            A filter by clause that is applied to any search query that matches the override rule.
        remove_matched_tokens:
          type: boolean
          description: >
            Indicates whether search query tokens that exist in the override's rule should be removed from the search query.
    SearchOverride:
      allOf:
        - $ref: "#/components/schemas/SearchOverrideSchema"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              readOnly: true
    SearchOverrideRule:
      type: object
      required:
        - query
        - match
      properties:
        query:
          type: string
          description: Indicates what search queries should be overridden
        match:
          type: string
          description: >
            Indicates whether the match on the query term should be `exact` or `contains`.
            If we want to match all queries that contained
            the word `apple`, we will use the `contains` match instead.
          enum:
            - exact
            - contains
    SearchOverrideInclude:
      type: object
      required:
        - id
        - position
      properties:
        id:
          type: string
          description: document id that should be included
        position:
          type: integer
          description: position number where document should be included in the search results
    SearchOverrideExclude:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: document id that should be excluded from the search results.
    SearchOverridesResponse:
      type: object
      required:
        - overrides
      properties:
        overrides:
          type: array
          x-go-type: "[]*SearchOverride"
          items:
            $ref: "#/components/schemas/SearchOverride"
    SearchSynonymSchema:
      type: object
      required:
        - synonyms
      properties:
        root:
          type: string
          description: For 1-way synonyms, indicates the root word that words in the `synonyms` parameter map to.
        synonyms:
          type: array
          description: Array of words that should be considered as synonyms.
          items:
            type: string
    SearchSynonym:
      allOf:
        - $ref: "#/components/schemas/SearchSynonymSchema"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              readOnly: true
    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
    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
          required:
            - id
            - value
            - value_prefix
          properties:
            id:
              type: integer
              format: int64
              readOnly: true
            value:
              type: string
              readOnly: true
            value_prefix:
              type: string
              readOnly: true
    ApiKeysResponse:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          x-go-type: "[]*ApiKey"
          items:
            $ref: "#/components/schemas/ApiKey"
    ScopedKeyParameters:
      type: object
      properties:
        filter_by:
          type: string
        expires_at:
          type: number
    SnapshotParameters:
      type: object
      properties:
        snapshot_path:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    MultiSearchResult:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
    SearchParameters:
      type: object
      required:
        - q
        - query_by

      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

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

        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

        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

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

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

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

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

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

        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

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

        prioritize_exact_match:
          description: >
            Set this parameter to true to ensure that an exact match is ranked above
            the others
          type: boolean
        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
        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

    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

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

        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

        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

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

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

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

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

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

        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

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

        prioritize_exact_match:
          description: >
            Set this parameter to true to ensure that an exact match is ranked above
            the others
          type: boolean
        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
    MultiSearchSearchesParameter:
      type: object
      required:
        - searches
      properties:
        searches:
          type: array
          items:
            $ref: "#/components/schemas/MultiSearchCollectionParameters"
    MultiSearchCollectionParameters:
      allOf:
        - $ref: "#/components/schemas/MultiSearchParameters"
        - type: object
          required:
            - collection
          properties:
            collection:
              type: string
              description: >
                The collection to search in.
    FacetCounts:
      type: object
      properties:
        counts:
          type: array
          items:
            type: object
            properties:
              count:
                type: integer
              highlighted:
                type: string
              value:
                type: string
        field_name:
          type: string
        stats:
          type: object
          properties:
            max:
              type: number
              format: double
            min:
              type: number
              format: double
            sum:
              type: number
              format: double
            total_values:
              type: integer
            avg:
              type: number
              format: double
  securitySchemes:
    api_key_header:
      type: apiKey
      name: X-TYPESENSE-API-KEY
      in: header