Source: http://localhost:1313/docs/rag/semantic-search.html

# Semantic Search

The semantic search API searches one or more collections and returns the most relevant indexed documents for the supplied search terms.

If your application already owns the candidate document strings, consider [Reflex](http://localhost:1313/docs/rag/reflex.md): a collection-less RAG search that ranks supplied documents without indexing or storage. Use managed semantic search when AIVAX should store and search a persistent corpus or when the corpus is too large to submit as candidates with every request.

Compare [vector search with the complete RAG pipeline](https://aivax.net/blog/a-vector-database-is-not-a-rag-system/) before deciding what to build.

Before searching, add documents to a [collection](http://localhost:1313/docs/rag/collections.md) and wait for indexing. Search with complete questions or phrases that reflect what a user would ask. The response can include the matched documents and their associated collection data for use in your application or AI Gateway flow.

For the supported request, response, authentication, and error contract, use the API Reference:

[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Semantic%20search)

## Filtering Documents

Use the `filter` field to search only documents that match tags, metadata, names, or dates, such as `tags has "finance" and createdAt >= now-30d`. See [Document Filters](http://localhost:1313/docs/filters/document-filters.md) for the syntax and examples.

## Reranking

A reranker can adjust the order of candidates returned by semantic search. It does not search additional documents or recover text that the retrieval stage did not select. See [Rerankers](http://localhost:1313/docs/rag/reranking.md) for selection guidance.

## Multiple Terms

Multiple terms cover alternative retrieval paths rather than requiring every term to match the same document. Use them for synonyms, alternative phrasings, or several acceptable ways to find an answer.

If the user's question combines several related conditions, keep them together in one search term. For example, prefer:

```text
How do I cancel an annual subscription without a penalty?
```

Over disconnected keywords:

```text
cancellation
annual subscription
penalty
```

## Search Quality

A complete query usually performs better than a list of disconnected keywords because it preserves the relationship between concepts.

If search returns poor results:

1. Confirm that the documents are indexed.
2. Query the collection directly before testing through an AI Gateway.
3. Compare complete questions with alternative phrasings.
4. Check whether the relevant document is too short, too long, or not self-contained.
5. Check whether the query language matches the document language.
6. If the gateway rewrites questions before searching, test with the plain query path to isolate rewriting issues.

## Collections MCP

To expose AIVAX collections as tools for an external MCP client, see [Collections MCP](http://localhost:1313/docs/mcp-utilities/collections-mcp.md).

For current service availability and account limits, see [Plans and Limits](http://localhost:1313/docs/limits.md).