Typesense API Reference for v{{ $page.typesenseVersion }}

This section of the documentation details all the API Endpoints available in Typesense and all the parameters you can use with them.

Use the links on the side navigation bar to get to the appropriate section you're looking for.

To learn how to install and run Typesense, see the Guide section instead.

What's new

This release contains new features, enhancements, performance improvements, bug fixes and important API changes for synonyms, curation rules and analytics rules.

New Features

• Diversify Search Results: Using Maximum Marginal Relevance (MMR), you can now diversify the top 250 hits on a pre-defined similarity metric. (Docs)
• Global Synonyms: Synonyms are now top-level resources, and can be shared between collections. (Docs)
• Global Curation Rules: Curations are also top-level resources now, and can be shared between multiple collections. (Docs)
• New features in JOINs:
  • facet_by now supports JOINed reference fields. (Docs)
  • Fetch related docs count for a document in a joined collection with the include_fields param. (Docs)
  • Support sorting and limit on joined fields with include_fields parameter. (Docs)
  • Support for altering reference fields in the collection schema.
  • New cascade_delete: false JOIN parameter for a reference field, to override the default behavior of document being cascade deleted in case all the documents it references are deleted. Requires async_reference parameter to be true. (Docs)
• New features in Union Search:
  • Support for group_by with Union search. (Docs)
  • Support for the pinned_hits search parameter in Union search.
  • Support for filtering out duplicates when using Union search with a new flag called remove_duplicates. (Docs)
• Facet Sampling: Make facet sampling dynamic using the new facet_sample_slope search parameter. (Docs)
• IPv6 Support: Typesense now supports binding to and serving requests over IPv6 addresses, enabling seamless integration and connectivity in modern IPv6-only or dual-stack networks.

Enhancements

• Support for (optionally) copying documents when cloning collections. (Docs)
• Support for ! as a standalone negation operator in filters, allowing field:![value] syntax as an alternative to field:!=[value].
• Support for Azure OpenAI models in Natural Language Search. (Docs)
• Support for GCP service account authentication in Natural Language Search models. (Docs)
• Support for GCP service account authentication for auto-embedding with GCP models. (Docs)
• Configurable token truncation for string fields to improve exact match filtering on long strings, using the new truncate parameter in the collection schema. (Docs)
• Return an error message when a field is declared that references another field of the same collection.
• New group_max_candidates search parameter which overrides the behavior of group_by queries introduced in v29.0 where found value is an approximation. When group_max_candidates is passed, found will be accurate up until its value. (Docs)
• Allow non-indexed nested fields to still be marked as required.
• Improved synonym matching logic: Previously, synonym matches with a higher number of tokens (query/synonym) would be ranked higher. Now, matches are ranked by how well they match the query/synonyms overall, not just by the number of matched tokens.
• Use Transliterator objects pool to enhance tokenization performance of Cyrillic and Chinese languages.
• Support for dynamic facet_return_parent fields. (Docs)
• Support for sending an empty array to avoid embedding generation for an optional auto embedding field when indexing a document.
• Highlight the actual search query when augmenting the search query with Natural Language search.
• Enhance image embedding models support by adding CLIP Multilingual Model support
• Support for synonym matching in curations (Docs)
• Support stemming with curations (Docs)

Bug Fixes

• Fix parsing of _eval() expressions when backticks are used to wrap strings containing parentheses.
• Ensure unique analytics IDs are generated when queries differ by filter_by or analytics_tag metadata to prevent aggregation issues.
• Fix search highlighting to use field-specific token separators instead of collection-level ones for consistent behavior.
• Return 201 status code when creating conversational models, personalization models, or natural language search models to follow REST conventions.
• Fix custom OpenAI-compatible endpoint URLs not being used for auto-embedding.
• Fix schema updates with embedding fields incorrectly requiring api_key validation for local models.
• Fix console logging to output info messages to stdout and warnings/errors to stderr instead of all to stderr.
• Fix phrase query highlighting to highlight only exact phrase matches instead of every individual keyword occurrence.
• Set user agent when initializing HTTP client for external API calls.
• Fix hyphen handling in negation searches to only apply special treatment when token starts with -.
• Fix query sub-tokenization to respect field-level symbols_to_index and token_separators configuration.
• Fix union search pagination bug where global pagination parameters were not passed to individual queries.
• Fix missing groups in case of high cardinality fields.
• Fix various deadlock scenarios related to async reference fields.
• Fix an edge case in group_by query along with infix search.
• Fix non-deterministic bucketing order when combining group_by with text match score bucketing, ensuring stable group pagination.
• Support id:![...] negation syntax for id filters.
• Fix remote embedder cache key handling for matryoshka models with different num_dim values to prevent dimension mismatches.
• Fix nested array highlights to respect highlight_affix_num_tokens for single-token matches.
• Fix phrase highlighting in nested array fields to return all matching snippets.
• Fix a crash while searching when updates are happening in parallel.
• Fixed the override matching for wildcard queries, dynamic filter, dynamic sort, and placeholders.
• Fix sort using _eval() for id fields.
• Fix missing vector distance in results when doing hybrid search with union search.
• Fix missing results when querying a stemmed field with drop_tokens_threshold set.
• Fix an edge case where field name can be empty.
• Fix synonym resolution when synonym_prefix is disabled.
• Fix allowing the addition of the same field multiple times when altering the collection.
• Fix an edge case that enables using resolved synonyms as prefixes when prefix search is enabled.
• Fix adding the field to schema despite an error, when sorting is enabled for a field that has auto as its type.
• Fix max_bytes parameters usage for the OpenAI's o-series and GPT-5 models.
• Prevent usage of temperature parameter for the o-series and GPT-5 models since it is not supported.
• Fix curation rule matching when doing semantic search with embedding generation.
• Fix rocksdb params assignment
• Fix missing joined collection fields in pinned hits
• Fix blocking indexing while generating embeddings.
• Fix issues of using outdated schemas when altering operations is ongoing while indexing documents.
• Fix curations with rerank_hybrid_matches
• Fix uninitialized analytics manager crash
• Validate that curation rules with match also include query, returning 400 otherwise.
• Fix dropping nested object fields to only remove dot-delimited children, preserving similarly-prefixed top-level fields.
• Fix conversation and natural language search model updates when the model ID changes, returning 409 on ID conflicts.
• [New in 30.1] Fixed precision issue with search latency metric in /stats.json endpoint

Deprecations / behavior changes

• ⚠️ Synonyms are no longer nested under Collections. We now have a top-level resource called a "Synonym Set" which is a list of synonyms that can be attached to one or more collections, or can be dynamically sent as a search parameter. Existing synonyms will be auto-migrated to synonym sets automatically on upgrading. (Docs)
• ⚠️ Synonym API Key Actions have changed. Since the synonym API route changed from /collections/{collection}/synonyms to /synonym_sets, API keys scoped to synonyms:* actions will not grant access to the new synonym set endpoints (resulting in 401 Unauthorized). You need to create new API keys using synonym_sets:* actions instead (e.g. synonym_sets:get, synonym_sets:list, synonym_sets:create, synonym_sets:delete). Since there is no update endpoint for API keys, you will need to create new keys and then delete the old ones. The old synonyms:* actions still apply to collection-level synonym endpoints. (Docs)
• ⚠️ Overrides (aka Curation Rules) are no longer nested under Collections. Similar to synonym sets, we now have a top-level resource called a "Curation Set" that can be attached to one or more collections, or can be dynamically sent as a search parameter. Existing overrides will be auto-migrated to curation sets automatically on upgrading. The override_tags parameter has also been renamed to curation_tags. (Docs)
• ⚠️ The structure of Analytics Rules has changed. Old rules will be automatically migrated to the new structure internally. Read more here. (Docs)
• The export endpoint doesn't stop streaming the response if an error is encountered while loading a document from disk. The error is logged and is also returned in the response stream.
• Collections having references to each other are not allowed. If mutual reference is detected, the reference field will not be indexed.

Upgrading

Before upgrading your existing Typesense cluster to v{{ $page.typesenseVersion }}, please review the behavior changes above to prepare your application for the upgrade.

We'd recommend testing on your development / staging environments before upgrading.

Follow this upgrade guide, depending on your mode of deployment.

:::warning ⚠️ Breaking Changes Please make sure to update your client libraries to the latest version, review the specific documentation links provided above and make any required changes to your code base if you programmatically create these resources using the API, before upgrading to this version. If self-hosting, perform a snapshot before upgrading for the Synonyms & Overrides to be migrated to v30. :::

Downgrading

If you use synonyms, overrides (curation rules) or analytics rules in previous versions of Typesense, we will auto-migrate them to the new resources (Synonym Sets, Curation Sets and the new format for analytics rules) on upgrading. However, if you make any changes to these resources, and then downgrade later, those changes will not be ported back to the old version after downgrade.

Besides the above caveat, you can safely downgrade to any version above v27.

:::tip This documentation itself is open source. If you find any issues, click on the Edit page button at the bottom of the page and send us a Pull Request. :::

<RedirectOldLinks />