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"
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"
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"
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"
/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"
/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"
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"
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"
/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/octet-stream:
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"}
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"
/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"
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"
/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"
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"
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"
/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"
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: company_name
type: string
facet: false
- name: num_employees
type: int32
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
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
default: []
symbols_to_index:
type: array
description: >
List of symbols or special characters to be indexed.
items:
type: string # characters only
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: 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
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
properties:
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
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: ``
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
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
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
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: ``
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
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: integer
min:
type: integer
sum:
type: integer
total_values:
type: integer
avg:
type: number
format: float
securitySchemes:
api_key_header:
type: apiKey
name: X-TYPESENSE-API-KEY
in: header