openapi: 3.0.3
info:
title: Typesense API
description: "An open source search engine for building delightful search experiences."
version: '27.0'
externalDocs:
description: Find out more about Typsesense
url: https://typesense.org
security:
- api_key_header: []
tags:
- name: collections
description: A collection is defined by a schema
externalDocs:
description: Find out more
url: https://typesense.org/api/#create-collection
- name: documents
description: A document is an individual record to be indexed and belongs to a collection
externalDocs:
description: Find out more
url: https://typesense.org/api/#index-document
- name: curation
description: Hand-curate search results based on conditional business rules
externalDocs:
description: Find out more
url: https://typesense.org/docs/0.23.0/api/#curation
- name: analytics
description: Typesense can aggregate search queries for both analytics purposes and for query suggestions.
externalDocs:
description: Find out more
url: https://typesense.org/docs/26.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/26.0/api/cluster-operations.html
- name: stopwords
description: Manage stopwords sets
externalDocs:
description: Find out more
url: https://typesense.org/docs/26.0/api/stopwords.html
- name: presets
description: Store and reference search parameters
externalDocs:
description: Find out more
url: https://typesense.org/docs/26.0/api/search.html#presets
- name: conversations
description: Conversational Search (RAG)
externalDocs:
description: Find out more
url: https://typesense.org/docs/27.0/api/conversational-search-rag.html
- name: synonyms
description: Manage synonyms
externalDocs:
description: Find out more
url: https://typesense.org/docs/27.0/api/synonyms.html
paths:
/collections:
get:
tags:
- collections
summary: List all collections
description:
Returns a summary of all your collections. The collections are
returned sorted by creation date, with the most recent collections appearing
first.
operationId: getCollections
responses:
'200':
description: List of all collections
content:
application/json:
schema:
type: array
x-go-type: "[]*CollectionResponse"
items:
$ref: "#/components/schemas/CollectionResponse"
post:
tags:
- collections
summary: Create a new collection
description:
When a collection is created, we give it a name and describe the
fields that will be indexed from the documents added to the collection.
operationId: createCollection
requestBody:
description: The collection object to be created
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionSchema"
required: true
responses:
'201':
description: Collection successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionResponse"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'409':
description: Collection already exists
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}:
get:
tags:
- collections
summary: Retrieve a single collection
description: Retrieve the details of a collection, given its name.
operationId: getCollection
parameters:
- name: collectionName
in: path
description: The name of the collection to retrieve
required: true
schema:
type: string
responses:
'200':
description: Collection fetched
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionResponse"
'404':
description: Collection not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
patch:
tags:
- collections
summary: Update a collection
description:
Update a collection's schema to modify the fields and their types.
operationId: updateCollection
parameters:
- name: collectionName
in: path
description: The name of the collection to update
required: true
schema:
type: string
requestBody:
description: The document object with fields to be updated
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionUpdateSchema"
required: true
responses:
'200':
description: The updated partial collection schema
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionUpdateSchema"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'404':
description: The collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- collections
summary: Delete a collection
description:
Permanently drops a collection. This action cannot be undone. For
large collections, this might have an impact on read latencies.
operationId: deleteCollection
parameters:
- name: collectionName
in: path
description: The name of the collection to delete
required: true
schema:
type: string
responses:
'200':
description: Collection deleted
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionResponse"
'404':
description: Collection not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/documents:
post:
tags:
- documents
summary: Index a document
description:
A document to be indexed in a given collection must conform to
the schema of the collection.
operationId: indexDocument
parameters:
- name: collectionName
in: path
description: The name of the collection to add the document to
required: true
schema:
type: string
- name: action
in: query
description: Additional action to perform
schema:
type: string
example: upsert
$ref: "#/components/schemas/IndexAction"
- name: dirty_values
in: query
description: Dealing with Dirty Data
schema:
$ref: "#/components/schemas/DirtyValues"
requestBody:
description: The document object to be indexed
content:
application/json:
schema:
type: object
description: Can be any key-value pair
x-go-type: "interface{}"
required: true
responses:
'201':
description: Document successfully created/indexed
content:
application/json:
schema:
type: object
description: Can be any key-value pair
'404':
description: Collection not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
patch:
tags:
- documents
summary: Update documents with conditional query
description:
The filter_by query parameter is used to filter to specify a condition against which the documents are matched.
The request body contains the fields that should be updated for any documents that match the filter condition.
This endpoint is only available if the Typesense server is version `0.25.0.rc12` or later.
operationId: updateDocuments
parameters:
- name: collectionName
in: path
description: The name of the collection to update documents in
required: true
schema:
type: string
- name: updateDocumentsParameters
in: query
schema:
type: object
properties:
filter_by:
type: string
example: "num_employees:>100 && country: [USA, UK]"
responses:
'200':
description:
The response contains a single field, `num_updated`, indicating the number of documents affected.
content:
application/json:
schema:
type: object
required:
- num_updated
properties:
num_updated:
type: integer
description: The number of documents that have been updated
example: 1
'400':
description: 'Bad request, see error message for details'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'404':
description: The collection was not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
requestBody:
description: The document fields to be updated
content:
application/json:
schema:
type: object
description: Can be any key-value pair
x-go-type: "interface{}"
required: true
delete:
tags:
- documents
summary: Delete a bunch of documents
description:
Delete a bunch of documents that match a specific filter condition.
Use the `batch_size` parameter to control the number of documents that
should deleted at a time. A larger value will speed up deletions, but will
impact performance of other operations running on the server.
operationId: deleteDocuments
parameters:
- name: collectionName
in: path
description: The name of the collection to delete documents from
required: true
schema:
type: string
- name: deleteDocumentsParameters
in: query
schema:
type: object
required:
- filter_by
properties:
filter_by:
type: string
example: "num_employees:>100 && country: [USA, UK]"
batch_size:
description:
Batch size parameter controls the number of documents that should be deleted
at a time. A larger value will speed up deletions, but will impact performance
of other operations running on the server.
type: integer
ignore_not_found:
type: boolean
responses:
'200':
description: Documents successfully deleted
content:
application/json:
schema:
type: object
required:
- num_deleted
properties:
num_deleted:
type: integer
'404':
description: Collection not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/documents/search:
get:
tags:
- documents
summary: Search for documents in a collection
description: Search for documents in a collection that match the search criteria.
operationId: searchCollection
parameters:
- name: collectionName
in: path
description: The name of the collection to search for the document under
required: true
schema:
type: string
- name: searchParameters
required: true
in: query
schema:
$ref: "#/components/schemas/SearchParameters"
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: "#/components/schemas/SearchResult"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'404':
description: The collection or field was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/overrides:
get:
tags:
- documents
- curation
summary: List all collection overrides
operationId: getSearchOverrides
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
responses:
'200':
description: List of all search overrides
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOverridesResponse"
/collections/{collectionName}/overrides/{overrideId}:
get:
tags:
- documents
- override
summary: Retrieve a single search override
description: Retrieve the details of a search override, given its id.
operationId: getSearchOverride
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: overrideId
in: path
description: The id of the search override
required: true
schema:
type: string
responses:
'200':
description: Search override fetched
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOverride"
put:
tags:
- documents
- curation
summary: Create or update an override to promote certain documents over others
description:
Create or update an override to promote certain documents over others.
Using overrides, you can include or exclude specific documents for a given query.
operationId: upsertSearchOverride
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: overrideId
in: path
description: The ID of the search override to create/update
required: true
schema:
type: string
requestBody:
description: The search override object to be created/updated
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOverrideSchema"
required: true
responses:
'200':
description: Created/updated search override
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOverride"
'404':
description: Search override not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- documents
- curation
summary: Delete an override associated with a collection
operationId: deleteSearchOverride
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: overrideId
in: path
description: The ID of the search override to delete
required: true
schema:
type: string
responses:
'200':
description: The ID of the deleted search override
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOverrideDeleteResponse"
'404':
description: Search override not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/synonyms:
get:
tags:
- synonyms
summary: List all collection synonyms
operationId: getSearchSynonyms
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
responses:
'200':
description: List of all search synonyms
content:
application/json:
schema:
$ref: "#/components/schemas/SearchSynonymsResponse"
'404':
description: Search synonyms was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/synonyms/{synonymId}:
get:
tags:
- synonyms
summary: Retrieve a single search synonym
description: Retrieve the details of a search synonym, given its id.
operationId: getSearchSynonym
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: synonymId
in: path
description: The id of the search synonym
required: true
schema:
type: string
responses:
'200':
description: Search synonym fetched
content:
application/json:
schema:
$ref: "#/components/schemas/SearchSynonym"
'404':
description: Search synonym was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
put:
tags:
- synonyms
summary: Create or update a synonym
description: Create or update a synonym to define search terms that should be considered equivalent.
operationId: upsertSearchSynonym
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: synonymId
in: path
description: The ID of the search synonym to create/update
required: true
schema:
type: string
requestBody:
description: The search synonym object to be created/updated
content:
application/json:
schema:
$ref: "#/components/schemas/SearchSynonymSchema"
required: true
responses:
'200':
description: Created/updated search synonym
content:
application/json:
schema:
$ref: "#/components/schemas/SearchSynonym"
'404':
description: Search synonym was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- synonyms
summary: Delete a synonym associated with a collection
operationId: deleteSearchSynonym
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: synonymId
in: path
description: The ID of the search synonym to delete
required: true
schema:
type: string
responses:
'200':
description: The ID of the deleted search synonym
content:
application/json:
schema:
$ref: "#/components/schemas/SearchSynonymDeleteResponse"
'404':
description: Search synonym not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/documents/export:
get:
tags:
- documents
summary: Export all documents in a collection
description: Export all documents in a collection in JSON lines format.
operationId: exportDocuments
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
- name: exportDocumentsParameters
in: query
schema:
type: object
properties:
filter_by:
description:
Filter conditions for refining your search results. Separate
multiple conditions with &&.
type: string
include_fields:
description: List of fields from the document to include in the search result
type: string
exclude_fields:
description: List of fields from the document to exclude in the search result
type: string
responses:
'200':
description: Exports all the documents in a given collection.
content:
application/octet-stream:
schema:
type: string
example: |
{"id": "124", "company_name": "Stark Industries", "num_employees": 5215, "country": "US"}
{"id": "125", "company_name": "Future Technology", "num_employees": 1232,"country": "UK"}
{"id": "126", "company_name": "Random Corp.", "num_employees": 531,"country": "AU"}
'404':
description: The collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/documents/import:
post:
tags:
- documents
summary: Import documents into a collection
description:
The documents to be imported must be formatted in a newline delimited
JSON structure. You can feed the output file from a Typesense export operation
directly as import.
operationId: importDocuments
parameters:
- name: collectionName
in: path
description: The name of the collection
required: true
schema:
type: string
# Do not change the index position of this param
- name: importDocumentsParameters
in: query
schema:
type: object
properties:
batch_size:
type: integer
return_id:
type: boolean
description:
Returning the id of the imported documents. If you want the
import response to return the ingested document's id in the
response, you can use the return_id parameter.
remote_embedding_batch_size:
type: integer
return_doc:
type: boolean
action:
$ref: "#/components/schemas/IndexAction"
dirty_values:
$ref: "#/components/schemas/DirtyValues"
requestBody:
description: The json array of documents or the JSONL file to import
content:
application/octet-stream:
schema:
type: string
description: The JSONL file to import
required: true
responses:
'200':
description:
Result of the import operation. Each line of the response indicates the result
of each document present in the request body (in the same order). If the import
of a single document fails, it does not affect the other documents.
If there is a failure, the response line will include a corresponding error
message and as well as the actual document content.
content:
application/octet-stream:
schema:
type: string
example: |
{"success": true}
{"success": false, "error": "Bad JSON.", "document": "[bad doc"}
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'404':
description: The collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/collections/{collectionName}/documents/{documentId}:
get:
tags:
- documents
summary: Retreive a document
description: Fetch an individual document from a collection by using its ID.
operationId: getDocument
parameters:
- name: collectionName
in: path
description: The name of the collection to search for the document under
required: true
schema:
type: string
- name: documentId
in: path
description: The Document ID
required: true
schema:
type: string
responses:
'200':
description: The document referenced by the ID
content:
application/json:
schema:
type: object
description: Can be any key-value pair
'404':
description: The document or collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
patch:
tags:
- documents
summary: Update a document
description:
Update an individual document from a collection by using its ID.
The update can be partial.
operationId: updateDocument
parameters:
- name: collectionName
in: path
description: The name of the collection to search for the document under
required: true
schema:
type: string
- name: documentId
in: path
description: The Document ID
required: true
schema:
type: string
- name: dirty_values
in: query
description: Dealing with Dirty Data
schema:
$ref: "#/components/schemas/DirtyValues"
requestBody:
description: The document object with fields to be updated
content:
application/json:
schema:
type: object
description: Can be any key-value pair
x-go-type: "interface{}"
required: true
responses:
'200':
description: The document referenced by the ID was updated
content:
application/json:
schema:
type: object
description: Can be any key-value pair
'404':
description: The document or collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- documents
summary: Delete a document
description: Delete an individual document from a collection by using its ID.
operationId: deleteDocument
parameters:
- name: collectionName
in: path
description: The name of the collection to search for the document under
required: true
schema:
type: string
- name: documentId
in: path
description: The Document ID
required: true
schema:
type: string
responses:
'200':
description: The document referenced by the ID was deleted
content:
application/json:
schema:
type: object
description: Can be any key-value pair
'404':
description: The document or collection was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/conversations/models:
get:
description: Retrieve all conversation models
operationId: retrieveAllConversationModels
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ConversationModelSchema'
type: array
x-go-type: '[]*ConversationModelSchema'
description: List of all conversation models
summary: List all conversation models
tags:
- conversations
post:
description: Create a Conversation Model
operationId: createConversationModel
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelCreateSchema'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelSchema'
description: Created Conversation Model
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
description: Bad request, see error message for details
tags:
- conversations
/conversations/models/{modelId}:
get:
description: Retrieve a conversation model
operationId: retrieveConversationModel
parameters:
- name: modelId
in: path
description: The id of the conversation model to retrieve
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelSchema'
description: A conversation model
summary: Retrieve a conversation model
tags:
- conversations
put:
description: Update a conversation model
operationId: updateConversationModel
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelUpdateSchema'
required: true
parameters:
- name: modelId
in: path
description: The id of the conversation model to update
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelSchema'
description: The conversation model was successfully updated
summary: Update a conversation model
tags:
- conversations
delete:
description: Delete a conversation model
operationId: deleteConversationModel
parameters:
- name: modelId
in: path
description: The id of the conversation model to delete
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationModelSchema'
description: The conversation model was successfully deleted
summary: Delete a conversation model
tags:
- conversations
/keys:
get:
tags:
- keys
summary: Retrieve (metadata about) all keys.
operationId: getKeys
responses:
'200':
description: List of all keys
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeysResponse"
post:
tags:
- keys
summary: Create an API Key
description:
Create an API Key with fine-grain access control. You can restrict access
on both a per-collection and per-action level.
The generated key is returned only during creation. You want to store
this key carefully in a secure place.
operationId: createKey
requestBody:
description: The object that describes API key scope
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeySchema"
responses:
'201':
description: Created API key
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'409':
description: API key generation conflict
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/keys/{keyId}:
get:
tags:
- keys
summary: Retrieve (metadata about) a key
description:
Retrieve (metadata about) a key. Only the key prefix is returned
when you retrieve a key. Due to security reasons, only the create endpoint
returns the full API key.
operationId: getKey
parameters:
- name: keyId
in: path
description: The ID of the key to retrieve
required: true
schema:
type: integer
format: int64
responses:
'200':
description: The key referenced by the ID
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKey"
'404':
description: The key was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- keys
summary: Delete an API key given its ID.
operationId: deleteKey
parameters:
- name: keyId
in: path
description: The ID of the key to delete
required: true
schema:
type: integer
format: int64
responses:
'200':
description: The key referenced by the ID
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeyDeleteResponse"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'404':
description: Key not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/aliases:
get:
tags:
- collections
summary: List all aliases
description: List all aliases and the corresponding collections that they map to.
operationId: getAliases
responses:
'200':
description: List of all collection aliases
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionAliasesResponse"
/aliases/{aliasName}:
put:
tags:
- collections
summary: Create or update a collection alias
description:
Create or update a collection alias. An alias is a virtual collection name that points
to a real collection. If you're familiar with symbolic links on Linux, it's very similar
to that. Aliases are useful when you want to reindex your data in the
background on a new collection and switch your application to it without any changes to
your code.
operationId: upsertAlias
parameters:
- name: aliasName
in: path
description: The name of the alias to create/update
required: true
schema:
type: string
requestBody:
description: Collection alias to be created/updated
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionAliasSchema"
responses:
'200':
description: The collection alias was created/updated
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionAlias"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
'404':
description: Alias not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
get:
tags:
- collections
summary: Retrieve an alias
description: Find out which collection an alias points to by fetching it
operationId: getAlias
parameters:
- name: aliasName
in: path
description: The name of the alias to retrieve
required: true
schema:
type: string
responses:
'200':
description: Collection alias fetched
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionAlias"
'404':
description: The alias was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- collections
summary: Delete an alias
operationId: deleteAlias
parameters:
- name: aliasName
in: path
description: The name of the alias to delete
required: true
schema:
type: string
responses:
'200':
description: Collection alias was deleted
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionAlias"
'404':
description: Alias not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/debug:
get:
tags:
- debug
summary: Print debugging information
description: Print debugging information
operationId: debug
responses:
'200':
description: Debugging information
content:
application/json:
schema:
type: object
properties:
version:
type: string
/health:
get:
tags:
- health
summary: Checks if Typesense server is ready to accept requests.
description: Checks if Typesense server is ready to accept requests.
operationId: health
responses:
'200':
description: Search service is ready for requests.
content:
application/json:
schema:
$ref: "#/components/schemas/HealthStatus"
/operations/snapshot:
post:
tags:
- operations
summary: Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
description:
Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
You can then backup the snapshot directory that gets created and later restore it
as a data directory, as needed.
operationId: takeSnapshot
parameters:
- name: snapshot_path
in: query
description: The directory on the server where the snapshot should be saved.
required: true
schema:
type: string
responses:
'201':
description: Snapshot is created.
content:
application/json:
schema:
$ref: "#/components/schemas/SuccessStatus"
/operations/vote:
post:
tags:
- operations
summary: Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
description:
Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
The follower node that you run this operation against will become the new leader,
once this command succeeds.
operationId: vote
responses:
'200':
description: Re-election is performed.
content:
application/json:
schema:
$ref: "#/components/schemas/SuccessStatus"
/multi_search:
post:
operationId: multiSearch
tags:
- documents
summary: send multiple search requests in a single HTTP request
description:
This is especially useful to avoid round-trip network latencies incurred otherwise if each of these requests are sent in separate HTTP requests.
You can also use this feature to do a federated search across multiple collections in a single HTTP request.
parameters:
- name: multiSearchParameters
required: true
in: query
schema:
$ref: "#/components/schemas/MultiSearchParameters"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/MultiSearchSearchesParameter"
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: "#/components/schemas/MultiSearchResult"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/analytics/events:
post:
tags:
- analytics
summary: Create an analytics event
description: Sending events for analytics e.g rank search results based on popularity.
operationId: createAnalyticsEvent
requestBody:
description: The Analytics event to be created
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsEventCreateSchema'
required: true
responses:
'201':
description: Analytics event successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsEventCreateResponse'
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
/analytics/rules:
post:
tags:
- analytics
summary: Creates an analytics rule
description:
When an analytics rule is created, we give it a name and describe the type, the source collections and the destination collection.
operationId: createAnalyticsRule
requestBody:
description: The Analytics rule to be created
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleSchema"
required: true
responses:
'201':
description: Analytics rule successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleSchema"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
get:
tags:
- analytics
summary: Retrieves all analytics rules
description:
Retrieve the details of all analytics rules
operationId: retrieveAnalyticsRules
responses:
'200':
description: Analytics rules fetched
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRulesRetrieveSchema"
/analytics/rules/{ruleName}:
put:
tags:
- analytics
summary: Upserts an analytics rule
description:
Upserts an analytics rule with the given name.
operationId: upsertAnalyticsRule
parameters:
- in: path
name: ruleName
description: The name of the analytics rule to upsert
schema:
type: string
required: true
requestBody:
description: The Analytics rule to be upserted
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleUpsertSchema"
required: true
responses:
'200':
description: Analytics rule successfully upserted
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleSchema"
'400':
description: Bad request, see error message for details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
get:
tags:
- analytics
summary: Retrieves an analytics rule
description:
Retrieve the details of an analytics rule, given it's name
operationId: retrieveAnalyticsRule
parameters:
- in: path
name: ruleName
description: The name of the analytics rule to retrieve
schema:
type: string
required: true
responses:
'200':
description: Analytics rule fetched
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleSchema"
'404':
description: Analytics rule not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- analytics
summary: Delete an analytics rule
description:
Permanently deletes an analytics rule, given it's name
operationId: deleteAnalyticsRule
parameters:
- in: path
name: ruleName
description: The name of the analytics rule to delete
schema:
type: string
required: true
responses:
'200':
description: Analytics rule deleted
content:
application/json:
schema:
$ref: "#/components/schemas/AnalyticsRuleDeleteResponse"
'404':
description: Analytics rule not found
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/metrics.json:
get:
tags:
- operations
summary: Get current RAM, CPU, Disk & Network usage metrics.
description:
Retrieve the metrics.
operationId: retrieveMetrics
responses:
'200':
description: Metrics fetched.
content:
application/json:
schema:
type: object
/stats.json:
get:
tags:
- operations
summary: Get stats about API endpoints.
description:
Retrieve the stats about API endpoints.
operationId: retrieveAPIStats
responses:
'200':
description: Stats fetched.
content:
application/json:
schema:
$ref: "#/components/schemas/APIStatsResponse"
/stopwords:
get:
tags:
- stopwords
summary: Retrieves all stopwords sets.
description:
Retrieve the details of all stopwords sets
operationId: retrieveStopwordsSets
responses:
'200':
description: Stopwords sets fetched.
content:
application/json:
schema:
$ref: "#/components/schemas/StopwordsSetsRetrieveAllSchema"
/stopwords/{setId}:
put:
tags:
- stopwords
summary: Upserts a stopwords set.
description:
When an analytics rule is created, we give it a name and describe the type, the source collections and the destination collection.
operationId: upsertStopwordsSet
parameters:
- in: path
name: setId
description: The ID of the stopwords set to upsert.
schema:
type: string
required: true
example: countries
requestBody:
description: The stopwords set to upsert.
content:
application/json:
schema:
$ref: "#/components/schemas/StopwordsSetUpsertSchema"
required: true
responses:
'200':
description: Stopwords set successfully upserted.
content:
application/json:
schema:
$ref: "#/components/schemas/StopwordsSetSchema"
'400':
description: Bad request, see error message for details.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
get:
tags:
- stopwords
summary: Retrieves a stopwords set.
description:
Retrieve the details of a stopwords set, given it's name.
operationId: retrieveStopwordsSet
parameters:
- in: path
name: setId
description: The ID of the stopwords set to retrieve.
schema:
type: string
required: true
example: countries
responses:
'200':
description: Stopwords set fetched.
content:
application/json:
schema:
$ref: "#/components/schemas/StopwordsSetRetrieveSchema"
'404':
description: Stopwords set not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
delete:
tags:
- stopwords
summary: Delete a stopwords set.
description:
Permanently deletes a stopwords set, given it's name.
operationId: deleteStopwordsSet
parameters:
- in: path
name: setId
description: The ID of the stopwords set to delete.
schema:
type: string
required: true
example: countries
responses:
'200':
description: Stopwords set rule deleted.
content:
application/json:
schema:
type: object
properties:
id:
type: string
required:
- id
example: |
{"id": "countries"}
'404':
description: Stopwords set not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiResponse"
/presets:
get:
tags:
- presets
summary: Retrieves all presets.
description: Retrieve the details of all presets
operationId: retrieveAllPresets
responses:
'200':
description: Presets fetched.
content:
application/json:
schema:
$ref: '#/components/schemas/PresetsRetrieveSchema'
/presets/{presetId}:
get:
tags:
- presets
summary: Retrieves a preset.
description: Retrieve the details of a preset, given it's name.
operationId: retrievePreset
parameters:
- in: path
name: presetId
description: The ID of the preset to retrieve.
schema:
type: string
required: true
example: listing_view
responses:
'200':
description: Preset fetched.
content:
application/json:
schema:
$ref: '#/components/schemas/PresetSchema'
'404':
description: Preset not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
put:
tags:
- presets
summary: Upserts a preset.
description: Create or update an existing preset.
operationId: upsertPreset
parameters:
- in: path
name: presetId
description: The name of the preset set to upsert.
schema:
type: string
required: true
example: listing_view
requestBody:
description: The stopwords set to upsert.
content:
application/json:
schema:
$ref: '#/components/schemas/PresetUpsertSchema'
required: true
responses:
'200':
description: Preset successfully upserted.
content:
application/json:
schema:
$ref: '#/components/schemas/PresetSchema'
'400':
description: Bad request, see error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
delete:
tags:
- presets
summary: Delete a preset.
description: Permanently deletes a preset, given it's name.
operationId: deletePreset
parameters:
- in: path
name: presetId
description: The ID of the preset to delete.
schema:
type: string
required: true
example: listing_view
responses:
'200':
description: Preset deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/PresetDeleteSchema'
'404':
description: Preset not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
components:
schemas:
CollectionSchema:
required:
- name
- fields
type: object
properties:
name:
type: string
description: Name of the collection
example: companies
fields:
type: array
description: A list of fields for querying, filtering and faceting
example:
- name: num_employees
type: int32
facet: false
- name: company_name
type: string
facet: false
- name: country
type: string
facet: true
items:
$ref: "#/components/schemas/Field"
default_sorting_field:
type: string
description:
The name of an int32 / float field that determines the order in which
the search results are ranked when a sort_by clause is not provided during
searching. This field must indicate some kind of popularity.
example: num_employees # Go with the first field name listed above to produce sane defaults
default: ""
token_separators:
type: array
description: >
List of symbols or special characters to be used for
splitting the text into individual words in addition to space and new-line characters.
items:
type: string # characters only
# Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
# enum: ["@", "!", ".", "/", ","]
minLength: 1
maxLength: 1
default: []
enable_nested_fields:
type: boolean
description:
Enables experimental support at a collection level for nested object or object array fields.
This field is only available if the Typesense server is version `0.24.0.rcn34` or later.
default: false
example: true
symbols_to_index:
type: array
description: >
List of symbols or special characters to be indexed.
items:
type: string # characters only
# Could `enum` be used instead, given it's symbols/special *characters*, e.g.:
# enum: ["@", "!", ".", "/", ","]
minLength: 1
maxLength: 1
default: []
voice_query_model:
$ref: "#/components/schemas/VoiceQueryModelCollectionConfig"
CollectionUpdateSchema:
required:
- fields
type: object
properties:
fields:
type: array
description: A list of fields for querying, filtering and faceting
example:
- name: company_name
type: string
facet: false
- name: num_employees
type: int32
facet: false
- name: country
type: string
facet: true
items:
$ref: "#/components/schemas/Field"
CollectionResponse:
allOf:
- $ref: "#/components/schemas/CollectionSchema"
- type: object
required:
- num_documents
- created_at
properties:
num_documents:
type: integer
description: Number of documents in the collection
format: int64
readOnly: true
created_at:
type: integer
description: Timestamp of when the collection was created (Unix epoch in seconds)
format: int64
readOnly: true
Field:
required:
- name
- type
type: object
properties:
name:
type: string
example: company_name
type:
type: string
example: string
optional:
type: boolean
example: true
facet:
type: boolean
example: false
index:
type: boolean
example: true
default: true
locale:
type: string
example: el
sort:
type: boolean
example: true
infix:
type: boolean
example: true
default: false
reference:
type: string
description: >
Name of a field in another collection that should be linked to this collection so that it can be joined during query.
num_dim:
type: integer
example: 256
drop:
type: boolean
example: true
# omitting default value since we want it to be null
store:
type: boolean
description: >
When set to false, the field value will not be stored on disk. Default: true.
vec_dist:
type: string
description: >
The distance metric to be used for vector search. Default: `cosine`. You can also use `ip` for inner product.
range_index:
type: boolean
description: >
Enables an index optimized for range filtering on numerical fields (e.g. rating:>3.5). Default: false.
stem:
type: boolean
description: >
Values are stemmed before indexing in-memory. Default: false.
embed:
type: object
required:
- from
- model_config
properties:
from:
type: array
items:
type: string
model_config:
type: object
required:
- model_name
properties:
model_name:
type: string
api_key:
type: string
url:
type: string
access_token:
type: string
refresh_token:
type: string
client_id:
type: string
client_secret:
type: string
project_id:
type: string
indexing_prefix:
type: string
query_prefix:
type: string
VoiceQueryModelCollectionConfig:
type: object
description: >
Configuration for the voice query model
properties:
model_name:
type: string
example: "ts/whisper/base.en"
CollectionAliasSchema:
type: object
required:
- collection_name
properties:
collection_name:
type: string
description: Name of the collection you wish to map the alias to
CollectionAlias:
type: object
required:
- collection_name
- name
properties:
name:
type: string
readOnly: true
description: Name of the collection alias
collection_name:
type: string
description: Name of the collection the alias mapped to
CollectionAliasesResponse:
type: object
required:
- aliases
properties:
aliases:
type: array
x-go-type: "[]*CollectionAlias"
items:
$ref: "#/components/schemas/CollectionAlias"
SearchResult:
type: object
properties:
facet_counts:
type: array
items:
$ref: "#/components/schemas/FacetCounts"
found:
type: integer
description: The number of documents found
found_docs:
type: integer
search_time_ms:
type: integer
description: The number of milliseconds the search took
out_of:
type: integer
description: The total number of documents in the collection
search_cutoff:
type: boolean
description: Whether the search was cut off
page:
type: integer
description: The search result page number
grouped_hits:
type: array
items:
$ref: "#/components/schemas/SearchGroupedHit"
hits:
type: array
description: The documents that matched the search query
items:
$ref: "#/components/schemas/SearchResultHit"
request_params:
type: object
required:
- collection_name
- q
- per_page
properties:
collection_name:
type: string
q:
type: string
per_page:
type: integer
voice_query:
type: object
properties:
transcribed_query:
type: string
conversation:
$ref: "#/components/schemas/SearchResultConversation"
SearchResultConversation:
type: object
required:
- answer
- conversation_history
- conversation_id
- query
properties:
answer:
type: string
conversation_history:
type: array
items:
type: object
conversation_id:
type: string
query:
type: string
SearchGroupedHit:
type: object
required:
- group_key
- hits
properties:
found:
type: integer
group_key:
type: array
items: {}
hits:
type: array
description: The documents that matched the search query
items:
$ref: "#/components/schemas/SearchResultHit"
SearchResultHit:
type: object
properties:
highlights:
type: array
description: (Deprecated) Contains highlighted portions of the search fields
items:
$ref: "#/components/schemas/SearchHighlight"
highlight:
type: object
description: Highlighted version of the matching document
additionalProperties: true
document:
type: object
description: Can be any key-value pair
additionalProperties:
type: object
text_match:
type: integer
format: int64
geo_distance_meters:
type: object
description: Can be any key-value pair
additionalProperties:
type: integer
vector_distance:
type: number
format: float
description: Distance between the query vector and matching document's vector value
example:
highlights:
company_name:
field: company_name
snippet: Stark 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: Stark Industries
snippets:
type: array
description: Present only for (array) string[] fields
example:
- Stark Industries
- Stark Corp
items:
type: string
value:
type: string
description: Full field value with highlighting, present only for (non-array) string fields
example: Stark Industries is a major supplier of space equipment.
values:
type: array
description: Full field value with highlighting, present only for (array) string[] fields
example:
- Stark Industries
- Stark Corp
items:
type: string
indices:
type: array
description: The indices property will be present only for string[]
fields and will contain the corresponding indices of the snippets
in the search field
example: 1
items:
type: integer
matched_tokens:
type: array
items:
type: object
x-go-type: "interface{}"
SearchOverrideSchema:
type: object
required:
- rule
properties:
rule:
$ref: "#/components/schemas/SearchOverrideRule"
includes:
type: array
description:
List of document `id`s that should be included in the search results with their
corresponding `position`s.
items:
$ref: "#/components/schemas/SearchOverrideInclude"
excludes:
type: array
description: List of document `id`s that should be excluded from the search results.
items:
$ref: "#/components/schemas/SearchOverrideExclude"
filter_by:
type: string
description: >
A filter by clause that is applied to any search query that matches the override rule.
remove_matched_tokens:
type: boolean
description: >
Indicates whether search query tokens that exist in the override's rule should be removed from the search query.
metadata:
type: object
description: >
Return a custom JSON object in the Search API response, when this rule is triggered. This can can be used to display a pre-defined message (eg: a promotion banner) on the front-end when a particular rule is triggered.
sort_by:
type: string
description: >
A sort by clause that is applied to any search query that matches the override rule.
replace_query:
type: string
description: >
Replaces the current search query with this value, when the search query matches the override rule.
filter_curated_hits:
type: boolean
description: >
When set to true, the filter conditions of the query is applied to the curated records as well.
Default: false.
effective_from_ts:
type: integer
description: >
A Unix timestamp that indicates the date/time from which the override will be active. You can use this to create override rules that start applying from a future point in time.
effective_to_ts:
type: integer
description: >
A Unix timestamp that indicates the date/time until which the override will be active. You can use this to create override rules that stop applying after a period of time.
stop_processing:
type: boolean
description: >
When set to true, override processing will stop at the first matching rule. When set to false override processing will continue and multiple override actions will be triggered in sequence.
Overrides are processed in the lexical sort order of their id field.
Default: true.
SearchOverride:
allOf:
- $ref: "#/components/schemas/SearchOverrideSchema"
- type: object
required:
- id
properties:
id:
type: string
readOnly: true
SearchOverrideDeleteResponse:
type: object
required:
- id
properties:
id:
type: string
description: The id of the override that was deleted
SearchOverrideRule:
type: object
properties:
tags:
type: array
description: List of tag values to associate with this override rule.
items:
type: string
query:
type: string
description: Indicates what search queries should be overridden
match:
type: string
description: >
Indicates whether the match on the query term should be `exact` or `contains`.
If we want to match all queries that contained
the word `apple`, we will use the `contains` match instead.
enum:
- exact
- contains
filter_by:
type: string
description: >
Indicates that the override should apply when the filter_by parameter in a search query exactly matches the string specified here (including backticks, spaces, brackets, etc).
SearchOverrideInclude:
type: object
required:
- id
- position
properties:
id:
type: string
description: document id that should be included
position:
type: integer
description: position number where document should be included in the search results
SearchOverrideExclude:
type: object
required:
- id
properties:
id:
type: string
description: document id that should be excluded from the search results.
SearchOverridesResponse:
type: object
required:
- overrides
properties:
overrides:
type: array
x-go-type: "[]*SearchOverride"
items:
$ref: "#/components/schemas/SearchOverride"
SearchSynonymSchema:
type: object
required:
- synonyms
properties:
root:
type: string
description: For 1-way synonyms, indicates the root word that words in the `synonyms` parameter map to.
synonyms:
type: array
description: Array of words that should be considered as synonyms.
items:
type: string
locale:
type: string
description: Locale for the synonym, leave blank to use the standard tokenizer.
symbols_to_index:
type: array
description: By default, special characters are dropped from synonyms. Use this attribute to specify which special characters should be indexed as is.
items:
type: string
SearchSynonym:
allOf:
- $ref: "#/components/schemas/SearchSynonymSchema"
- type: object
required:
- id
properties:
id:
type: string
readOnly: true
SearchSynonymDeleteResponse:
type: object
required:
- id
properties:
id:
type: string
description: The id of the synonym that was deleted
SearchSynonymsResponse:
type: object
required:
- synonyms
properties:
synonyms:
type: array
x-go-type: "[]*SearchSynonym"
items:
$ref: "#/components/schemas/SearchSynonym"
HealthStatus:
type: object
required:
- ok
properties:
ok:
type: boolean
SuccessStatus:
type: object
required:
- success
properties:
success:
type: boolean
ApiResponse:
type: object
required:
- message
properties:
message:
type: string
ApiKeySchema:
type: object
required:
- actions
- collections
- description
properties:
value:
type: string
description:
type: string
actions:
type: array
items:
type: string
collections:
type: array
items:
type: string
expires_at:
type: integer
format: int64
ApiKey:
allOf:
- $ref: "#/components/schemas/ApiKeySchema"
- type: object
properties:
id:
type: integer
format: int64
readOnly: true
value_prefix:
type: string
readOnly: true
ApiKeyDeleteResponse:
type: object
required:
- id
properties:
id:
type: integer
format: int64
description: The id of the API key that was deleted
ApiKeysResponse:
type: object
required:
- keys
properties:
keys:
type: array
x-go-type: "[]*ApiKey"
items:
$ref: "#/components/schemas/ApiKey"
ScopedKeyParameters:
type: object
properties:
filter_by:
type: string
expires_at:
type: integer
format: int64
SnapshotParameters:
type: object
properties:
snapshot_path:
type: string
ErrorResponse:
type: object
properties:
message:
type: string
MultiSearchResult:
type: object
required:
- results
properties:
results:
type: array
items:
$ref: "#/components/schemas/SearchResult"
conversation:
$ref: "#/components/schemas/SearchResultConversation"
SearchParameters:
type: object
properties:
q:
description: The query text to search for in the collection.
Use * as the search string to return all documents.
This is typically useful when used in conjunction with filter_by.
type: string
query_by:
description: A list of `string` fields that should be queried
against. Multiple fields are separated with a comma.
type: string
query_by_weights:
description:
The relative weight to give each `query_by` field when ranking results.
This can be used to boost fields in priority, when looking for matches.
Multiple fields are separated with a comma.
type: string
text_match_type:
description:
In a multi-field matching context, this parameter determines how the representative text match
score of a record is calculated. Possible values are max_score (default) or max_weight.
type: string
prefix:
description:
Boolean field to indicate that the last word in the query should
be treated as a prefix, and not as a whole word. This is used for building
autocomplete and instant search interfaces. Defaults to true.
type: string
infix:
description:
If infix index is enabled for this field, infix searching can be done on a per-field
basis by sending a comma separated string parameter called infix to the search query.
This parameter can have 3 values; `off` infix search is disabled, which is default
`always` infix search is performed along with regular search
`fallback` infix search is performed if regular search does not produce results
type: string
max_extra_prefix:
description:
There are also 2 parameters that allow you to control the extent of infix searching
max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
or after the query that can be present in the token. For example query "K2100" has 2 extra
symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
type: integer
max_extra_suffix:
description:
There are also 2 parameters that allow you to control the extent of infix searching
max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
or after the query that can be present in the token. For example query "K2100" has 2 extra
symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
type: integer
filter_by:
description:
Filter conditions for refining youropen api validator search results. Separate
multiple conditions with &&.
type: string
example: "num_employees:>100 && country: [USA, UK]"
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: ``
type: string
highlight_end_tag:
description: >
The end tag used for the highlighted snippets.
Default: ``
type: string
enable_highlight_v1:
description: >
Flag for enabling/disabling the deprecated, old highlight structure in the response.
Default: true
type: boolean
default: true
snippet_threshold:
description: >
Field values under this length will be fully highlighted, instead of showing
a snippet of relevant portion. Default: 30
type: integer
drop_tokens_threshold:
description: >
If the number of results found for a specific query is less than
this number, Typesense will attempt to drop the tokens in the query until
enough results are found. Tokens that have the least individual hits
are dropped first. Set to 0 to disable. Default: 10
type: integer
drop_tokens_mode:
$ref: "#/components/schemas/DropTokensMode"
typo_tokens_threshold:
description: >
If the number of results found for a specific query is less than this number,
Typesense will attempt to look for tokens with more typos until
enough results are found. Default: 100
type: integer
enable_typos_for_alpha_numerical_tokens:
type: boolean
description: >
Set this parameter to false to disable typos on alphanumerical query tokens. Default: true.
filter_curated_hits:
type: boolean
description: >
Whether the filter_by condition of the search query should be applicable to curated results (override definitions, pinned hits, hidden hits, etc.). Default: false
enable_synonyms:
type: boolean
description: >
If you have some synonyms defined but want to disable all of them for a particular search query, set enable_synonyms to false. Default: true
synonym_prefix:
type: boolean
description: >
Allow synonym resolution on word prefixes in the query. Default: false
synonym_num_typos:
type: integer
description: >
Allow synonym resolution on typo-corrected words in the query. Default: 0
pinned_hits:
description: >
A list of records to unconditionally include in the search results
at specific positions. An example use case would be to feature or promote
certain items on the top of search results.
A list of `record_id:hit_position`. Eg: to include a record with ID 123
at Position 1 and another record with ID 456 at Position 5,
you'd specify `123:1,456:5`.
You could also use the Overrides feature to override search results based
on rules. Overrides are applied first, followed by `pinned_hits` and
finally `hidden_hits`.
type: string
hidden_hits:
description: >
A list of records to unconditionally hide from search results.
A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456,
you'd specify `123,456`.
You could also use the Overrides feature to override search results based
on rules. Overrides are applied first, followed by `pinned_hits` and
finally `hidden_hits`.
type: string
override_tags:
description: Comma separated list of tags to trigger the curations rules that match the tags.
type: string
highlight_fields:
description: >
A list of custom fields that must be highlighted even if you don't query
for them
type: string
split_join_tokens:
description: >
Treat space as typo: search for q=basket ball if q=basketball is not found or vice-versa.
Splitting/joining of tokens will only be attempted if the original query produces no results.
To always trigger this behavior, set value to `always``.
To disable, set value to `off`. Default is `fallback`.
type: string
pre_segmented_query:
description: >
You can index content from any logographic language into Typesense if you
are able to segment / split the text into space-separated words yourself
before indexing and querying.
Set this parameter to true to do the same
type: boolean
preset:
description: >
Search using a bunch of search parameters by setting this parameter to
the name of the existing Preset.
type: string
enable_overrides:
description: >
If you have some overrides defined but want to disable all of them during
query time, you can do that by setting this parameter to false
type: boolean
default: false
prioritize_exact_match:
description: >
Set this parameter to true to ensure that an exact match is ranked above
the others
type: boolean
default: true
max_candidates:
description: >
Control the number of words that Typesense considers for typo and prefix searching.
type: integer
prioritize_token_position:
description: >
Make Typesense prioritize documents where the query words appear earlier in the text.
type: boolean
default: false
prioritize_num_matching_fields:
description: >
Make Typesense prioritize documents where the query words appear in more number of fields.
type: boolean
default: true
enable_typos_for_numerical_tokens:
description: >
Make Typesense disable typos for numerical tokens.
type: boolean
default: true
exhaustive_search:
description: >
Setting this to true will make Typesense consider all prefixes and typo
corrections of the words in the query without stopping early when enough results are found
(drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
type: boolean
search_cutoff_ms:
description: >
Typesense will attempt to return results early if the cutoff time has elapsed.
This is not a strict guarantee and facet computation is not bound by this parameter.
type: integer
use_cache:
description: >
Enable server side caching of search query results. By default, caching is disabled.
type: boolean
cache_ttl:
description: >
The duration (in seconds) that determines how long the search query is cached.
This value can be set on a per-query basis. Default: 60.
type: integer
min_len_1typo:
description: >
Minimum word length for 1-typo correction to be applied.
The value of num_typos is still treated as the maximum allowed typos.
type: integer
min_len_2typo:
description: >
Minimum word length for 2-typo correction to be applied.
The value of num_typos is still treated as the maximum allowed typos.
type: integer
vector_query:
description: >
Vector query expression for fetching documents "closest" to a given query/document vector.
type: string
remote_embedding_timeout_ms:
description: >
Timeout (in milliseconds) for fetching remote embeddings.
type: integer
remote_embedding_num_tries:
description: >
Number of times to retry fetching remote embeddings.
type: integer
facet_strategy:
description: >
Choose the underlying faceting strategy used. Comma separated string of allows values:
exhaustive, top_values or automatic (default).
type: string
stopwords:
description: >
Name of the stopwords set to apply for this search,
the keywords present in the set will be removed from the search query.
type: string
facet_return_parent:
description: >
Comma separated string of nested facet fields whose parent object should be returned in facet response.
type: string
voice_query:
description: >
The base64 encoded audio file in 16 khz 16-bit WAV format.
type: string
conversation:
description: >
Enable conversational search.
type: boolean
conversation_model_id:
description: >
The Id of Conversation Model to be used.
type: string
conversation_id:
description: >
The Id of a previous conversation to continue, this tells Typesense to include prior context when communicating with the LLM.
type: string
MultiSearchParameters:
description: >
Parameters for the multi search API.
type: object
properties:
q:
description: The query text to search for in the collection.
Use * as the search string to return all documents.
This is typically useful when used in conjunction with filter_by.
type: string
query_by:
description: A list of `string` fields that should be queried
against. Multiple fields are separated with a comma.
type: string
query_by_weights:
description:
The relative weight to give each `query_by` field when ranking results.
This can be used to boost fields in priority, when looking for matches.
Multiple fields are separated with a comma.
type: string
text_match_type:
description:
In a multi-field matching context, this parameter determines how the representative text match
score of a record is calculated. Possible values are max_score (default) or max_weight.
type: string
prefix:
description:
Boolean field to indicate that the last word in the query should
be treated as a prefix, and not as a whole word. This is used for building
autocomplete and instant search interfaces. Defaults to true.
type: string
infix:
description:
If infix index is enabled for this field, infix searching can be done on a per-field
basis by sending a comma separated string parameter called infix to the search query.
This parameter can have 3 values; `off` infix search is disabled, which is default
`always` infix search is performed along with regular search
`fallback` infix search is performed if regular search does not produce results
type: string
max_extra_prefix:
description:
There are also 2 parameters that allow you to control the extent of infix searching
max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
or after the query that can be present in the token. For example query "K2100" has 2 extra
symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
type: integer
max_extra_suffix:
description:
There are also 2 parameters that allow you to control the extent of infix searching
max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before
or after the query that can be present in the token. For example query "K2100" has 2 extra
symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.
type: integer
filter_by:
description:
Filter conditions for refining youropen api validator search results. Separate
multiple conditions with &&.
type: string
example: "num_employees:>100 && country: [USA, UK]"
sort_by:
description:
A list of numerical fields and their corresponding sort orders
that will be used for ordering your results.
Up to 3 sort fields can be specified.
The text similarity score is exposed as a special `_text_match` field that
you can use in the list of sorting fields.
If no `sort_by` parameter is specified, results are sorted by
`_text_match:desc,default_sorting_field:desc`
type: string
facet_by:
description:
A list of fields that will be used for faceting your results
on. Separate multiple fields with a comma.
type: string
max_facet_values:
description: Maximum number of facet values to be returned.
type: integer
facet_query:
description:
Facet values that are returned can now be filtered via this parameter.
The matching facet text is also highlighted. For example, when faceting
by `category`, you can set `facet_query=category:shoe` to return only
facet values that contain the prefix "shoe".
type: string
num_typos:
description: >
The number of typographical errors (1 or 2) that would be tolerated.
Default: 2
type: string
page:
description: Results from this specific page number would be fetched.
type: integer
per_page:
description: "Number of results to fetch per page. Default: 10"
type: integer
limit:
description: >
Number of hits to fetch. Can be used as an alternative to the per_page parameter.
Default: 10.
type: integer
offset:
description: Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.
type: integer
group_by:
description:
You can aggregate search results into groups or buckets by specify
one or more `group_by` fields. Separate multiple fields with a comma.
To group on a particular field, it must be a faceted field.
type: string
group_limit:
description: >
Maximum number of hits to be returned for every group. If the `group_limit` is
set as `K` then only the top K hits in each group are returned in the response.
Default: 3
type: integer
group_missing_values:
description: >
Setting this parameter to true will place all documents that have a null value in the group_by field, into a single group.
Setting this parameter to false, will cause each document with a null value in the group_by field to not be grouped with other documents.
Default: true
type: boolean
include_fields:
description: List of fields from the document to include in the search result
type: string
exclude_fields:
description: List of fields from the document to exclude in the search result
type: string
highlight_full_fields:
description: List of fields which should be highlighted fully without snippeting
type: string
highlight_affix_num_tokens:
description: >
The number of tokens that should surround the highlighted text on each side.
Default: 4
type: integer
highlight_start_tag:
description: >
The start tag used for the highlighted snippets.
Default: ``
type: string
highlight_end_tag:
description: >
The end tag used for the highlighted snippets.
Default: ``
type: string
snippet_threshold:
description: >
Field values under this length will be fully highlighted, instead of showing
a snippet of relevant portion. Default: 30
type: integer
drop_tokens_threshold:
description: >
If the number of results found for a specific query is less than
this number, Typesense will attempt to drop the tokens in the query until
enough results are found. Tokens that have the least individual hits
are dropped first. Set to 0 to disable. Default: 10
type: integer
drop_tokens_mode:
$ref: "#/components/schemas/DropTokensMode"
typo_tokens_threshold:
description: >
If the number of results found for a specific query is less than this number,
Typesense will attempt to look for tokens with more typos until
enough results are found. Default: 100
type: integer
enable_typos_for_alpha_numerical_tokens:
type: boolean
description: >
Set this parameter to false to disable typos on alphanumerical query tokens. Default: true.
filter_curated_hits:
type: boolean
description: >
Whether the filter_by condition of the search query should be applicable to curated results (override definitions, pinned hits, hidden hits, etc.). Default: false
enable_synonyms:
type: boolean
description: >
If you have some synonyms defined but want to disable all of them for a particular search query, set enable_synonyms to false. Default: true
synonym_prefix:
type: boolean
description: >
Allow synonym resolution on word prefixes in the query. Default: false
synonym_num_typos:
type: integer
description: >
Allow synonym resolution on typo-corrected words in the query. Default: 0
pinned_hits:
description: >
A list of records to unconditionally include in the search results
at specific positions. An example use case would be to feature or promote
certain items on the top of search results.
A list of `record_id:hit_position`. Eg: to include a record with ID 123
at Position 1 and another record with ID 456 at Position 5,
you'd specify `123:1,456:5`.
You could also use the Overrides feature to override search results based
on rules. Overrides are applied first, followed by `pinned_hits` and
finally `hidden_hits`.
type: string
hidden_hits:
description: >
A list of records to unconditionally hide from search results.
A list of `record_id`s to hide. Eg: to hide records with IDs 123 and 456,
you'd specify `123,456`.
You could also use the Overrides feature to override search results based
on rules. Overrides are applied first, followed by `pinned_hits` and
finally `hidden_hits`.
type: string
override_tags:
description: Comma separated list of tags to trigger the curations rules that match the tags.
type: string
highlight_fields:
description: >
A list of custom fields that must be highlighted even if you don't query
for them
type: string
pre_segmented_query:
description: >
You can index content from any logographic language into Typesense if you
are able to segment / split the text into space-separated words yourself
before indexing and querying.
Set this parameter to true to do the same
type: boolean
default: false
preset:
description: >
Search using a bunch of search parameters by setting this parameter to
the name of the existing Preset.
type: string
enable_overrides:
description: >
If you have some overrides defined but want to disable all of them during
query time, you can do that by setting this parameter to false
type: boolean
default: false
prioritize_exact_match:
description: >
Set this parameter to true to ensure that an exact match is ranked above
the others
type: boolean
default: true
prioritize_token_position:
description: >
Make Typesense prioritize documents where the query words appear earlier in the text.
type: boolean
default: false
prioritize_num_matching_fields:
description: >
Make Typesense prioritize documents where the query words appear in more number of fields.
type: boolean
default: true
enable_typos_for_numerical_tokens:
description: >
Make Typesense disable typos for numerical tokens.
type: boolean
default: true
exhaustive_search:
description: >
Setting this to true will make Typesense consider all prefixes and typo
corrections of the words in the query without stopping early when enough results are found
(drop_tokens_threshold and typo_tokens_threshold configurations are ignored).
type: boolean
search_cutoff_ms:
description: >
Typesense will attempt to return results early if the cutoff time has elapsed.
This is not a strict guarantee and facet computation is not bound by this parameter.
type: integer
use_cache:
description: >
Enable server side caching of search query results. By default, caching is disabled.
type: boolean
cache_ttl:
description: >
The duration (in seconds) that determines how long the search query is cached.
This value can be set on a per-query basis. Default: 60.
type: integer
min_len_1typo:
description: >
Minimum word length for 1-typo correction to be applied.
The value of num_typos is still treated as the maximum allowed typos.
type: integer
min_len_2typo:
description: >
Minimum word length for 2-typo correction to be applied.
The value of num_typos is still treated as the maximum allowed typos.
type: integer
vector_query:
description: >
Vector query expression for fetching documents "closest" to a given query/document vector.
type: string
remote_embedding_timeout_ms:
description: >
Timeout (in milliseconds) for fetching remote embeddings.
type: integer
remote_embedding_num_tries:
description: >
Number of times to retry fetching remote embeddings.
type: integer
facet_strategy:
description: >
Choose the underlying faceting strategy used. Comma separated string of allows values:
exhaustive, top_values or automatic (default).
type: string
stopwords:
description: >
Name of the stopwords set to apply for this search,
the keywords present in the set will be removed from the search query.
type: string
facet_return_parent:
description: >
Comma separated string of nested facet fields whose parent object should be returned in facet response.
type: string
voice_query:
description: >
The base64 encoded audio file in 16 khz 16-bit WAV format.
type: string
conversation:
description: >
Enable conversational search.
type: boolean
conversation_model_id:
description: >
The Id of Conversation Model to be used.
type: string
conversation_id:
description: >
The Id of a previous conversation to continue, this tells Typesense to include prior context when communicating with the LLM.
type: string
MultiSearchSearchesParameter:
type: object
required:
- searches
properties:
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
parent:
type: object
field_name:
type: string
stats:
type: object
properties:
max:
type: number
format: double
min:
type: number
format: double
sum:
type: number
format: double
total_values:
type: integer
avg:
type: number
format: double
AnalyticsEventCreateResponse:
type: object
required:
- ok
properties:
ok:
type: boolean
AnalyticsEventCreateSchema:
type: object
required:
- type
- name
- data
properties:
type:
type: string
name:
type: string
data:
type: object
AnalyticsRuleUpsertSchema:
type: object
required:
- type
- params
properties:
type:
type: string
enum:
- popular_queries
- nohits_queries
- counter
params:
$ref: "#/components/schemas/AnalyticsRuleParameters"
AnalyticsRuleParameters:
type: object
required:
- source
- destination
properties:
source:
$ref: '#/components/schemas/AnalyticsRuleParametersSource'
destination:
$ref: '#/components/schemas/AnalyticsRuleParametersDestination'
limit:
type: integer
expand_query:
type: boolean
AnalyticsRuleParametersSource:
type: object
required:
- collections
properties:
collections:
type: array
items:
type: string
events:
type: array
items:
type: object
required:
- type
- weight
- name
properties:
type:
type: string
weight:
type: number
format: float
name:
type: string
AnalyticsRuleParametersDestination:
type: object
required:
- collection
properties:
collection:
type: string
counter_field:
type: string
AnalyticsRuleDeleteResponse:
type: object
required:
- name
properties:
name:
type: string
AnalyticsRuleSchema:
allOf:
- $ref: '#/components/schemas/AnalyticsRuleUpsertSchema'
- type: object
required:
- name
properties:
name:
type: string
AnalyticsRulesRetrieveSchema:
type: object
properties:
rules:
type: array
items:
$ref: "#/components/schemas/AnalyticsRuleSchema"
x-go-type: '[]*AnalyticsRuleSchema'
APIStatsResponse:
type: object
properties:
delete_latency_ms:
type: number
format: double
delete_requests_per_second:
type: number
format: double
import_latency_ms:
type: number
format: double
import_requests_per_second:
type: number
format: double
latency_ms:
type: object
x-go-type: "map[string]float64"
overloaded_requests_per_second:
type: number
format: double
pending_write_batches:
type: number
format: double
requests_per_second:
type: object
x-go-type: "map[string]float64"
search_latency_ms:
type: number
format: double
search_requests_per_second:
type: number
format: double
total_requests_per_second:
type: number
format: double
write_latency_ms:
type: number
format: double
write_requests_per_second:
type: number
format: double
StopwordsSetUpsertSchema:
type: object
properties:
stopwords:
type: array
items:
type: string
locale:
type: string
required:
- stopwords
example: |
{"stopwords": ["Germany", "France", "Italy"], "locale": "en"}
StopwordsSetSchema:
type: object
properties:
id:
type: string
stopwords:
type: array
items:
type: string
locale:
type: string
required:
- id
- stopwords
example: |
{"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}
StopwordsSetRetrieveSchema:
type: object
properties:
stopwords:
$ref: "#/components/schemas/StopwordsSetSchema"
required:
- stopwords
example: |
{"stopwords": {"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}}
StopwordsSetsRetrieveAllSchema:
type: object
properties:
stopwords:
type: array
items:
$ref: "#/components/schemas/StopwordsSetSchema"
required:
- stopwords
example: |
{"stopwords": [{"id": "countries", "stopwords": ["Germany", "France", "Italy"], "locale": "en"}]}
PresetUpsertSchema:
properties:
value:
oneOf:
- $ref: '#/components/schemas/SearchParameters'
- $ref: '#/components/schemas/MultiSearchSearchesParameter'
required:
- value
PresetSchema:
allOf:
- $ref: '#/components/schemas/PresetUpsertSchema'
- type: object
required:
- name
properties:
name:
type: string
PresetsRetrieveSchema:
type: object
required:
- presets
properties:
presets:
type: array
items:
$ref: '#/components/schemas/PresetSchema'
x-go-type: '[]*PresetSchema'
PresetDeleteSchema:
type: object
required:
- name
properties:
name:
type: string
# client libraries already have .create, .upsert,... methods so we omit the `action` param
DocumentIndexParameters:
type: object
properties:
dirty_values:
$ref: "#/components/schemas/DirtyValues"
DirtyValues:
type: string
enum: [coerce_or_reject, coerce_or_drop, drop, reject]
IndexAction:
type: string
enum: [create, update, upsert, emplace]
DropTokensMode:
type: string
enum: [right_to_left, left_to_right, both_sides:3]
description: >
Dictates the direction in which the words in the query must be dropped when the original words in the query do not appear in any document.
Values: right_to_left (default), left_to_right, both_sides:3
A note on both_sides:3 - for queries upto 3 tokens (words) in length, this mode will drop tokens from both sides and exhaustively rank all matching results.
If query length is greater than 3 words, Typesense will just fallback to default behavior of right_to_left
ConversationModelCreateSchema:
required:
- model_name
- max_bytes
allOf:
- $ref: '#/components/schemas/ConversationModelUpdateSchema'
- type: object
required:
- model_name
- max_bytes
- history_collection
properties:
model_name:
description: Name of the LLM model offered by OpenAI, Cloudflare or vLLM
type: string
max_bytes:
description: |
The maximum number of bytes to send to the LLM in every API call. Consult the LLM's documentation on the number of bytes supported in the context window.
type: integer
history_collection:
type: string
description: Typesense collection that stores the historical conversations
ConversationModelUpdateSchema:
type: object
properties:
id:
type: string
description: An explicit id for the model, otherwise the API will return a response with an auto-generated conversation model id.
model_name:
description: Name of the LLM model offered by OpenAI, Cloudflare or vLLM
type: string
api_key:
description: The LLM service's API Key
type: string
history_collection:
type: string
description: Typesense collection that stores the historical conversations
account_id:
description: LLM service's account ID (only applicable for Cloudflare)
type: string
system_prompt:
description: The system prompt that contains special instructions to the LLM
type: string
ttl:
type: integer
description: |
Time interval in seconds after which the messages would be deleted. Default: 86400 (24 hours)
max_bytes:
description: |
The maximum number of bytes to send to the LLM in every API call. Consult the LLM's documentation on the number of bytes supported in the context window.
type: integer
vllm_url:
description: URL of vLLM service
type: string
ConversationModelSchema:
allOf:
- $ref: '#/components/schemas/ConversationModelCreateSchema'
- type: object
required:
- id
properties:
id:
type: string
description: An explicit id for the model, otherwise the API will return a response with an auto-generated conversation model id.
securitySchemes:
api_key_header:
type: apiKey
name: X-TYPESENSE-API-KEY
in: header