Search
Search returns indexed documents from one or more collections. Use managed search when AIVAX should store and search a persistent corpus, or when the corpus is too large to submit as candidates with every request.
AIVAX searches through three endpoints:
| Endpoint | Path | Use it to | Cost |
|---|---|---|---|
| Query collections | POST /api/v2/query | Find the documents that best answer a question. | Query embedding and, when used, reranking. |
| Find similar documents | POST /api/v2/query/similar | Find documents close in meaning to a document you already have. | No embedding or reranking cost. |
| Browse documents | POST /api/v2/query/browse | List documents in a fixed order, optionally filtered, without relevance. | No embedding or reranking cost. |
RAG answer generation and collections attached to an AI Gateway use the same retrieval engine.
If your application already owns the candidate document strings, consider Reflex. Reflex is a collection-less search that ranks supplied documents without indexing or storage.
Before searching:
- Add documents to a collection.
- Wait for indexing. Only indexed documents are returned.
- Compare vector search with the complete RAG pipeline before deciding what to build.
Query collections #
Use this endpoint to find the documents that best answer a question.
A query runs in this order:
- If a filter is set, AIVAX restricts each collection to the documents that match it.
- Each search term is embedded and compared with the remaining documents.
- Documents below
minScoreare discarded, and the closestcandidatesdocuments form the candidate pool. - The reranker reorders the pool, unless reranking is disabled.
- The pool is sorted and returned in pages of
limitresults.
{
"collections": [ "<collection-id>" ],
"terms": "How do I request a refund?"
}Use these options to narrow the corpus, size the pool, and page the results.
| Option | Default | Description |
|---|---|---|
collections | Required | Collection IDs owned by the account. An item can also be { "id": "<collection-id>", "filter": "..." } to filter only that collection. |
terms | Required | One search text or a list of alternative texts. |
filter | — | An advanced filter expression, or a list of expressions that must all match. |
minScore | 0.2 | Minimum vector similarity, from 0 to 0.99, for a document to enter the candidate pool. Raise it to drop weak matches; lower it when relevant documents are missing. |
candidates | limit × 3 | Size of the candidate pool, from limit to 1000. A larger pool gives the reranker and later pages more documents to work with. |
reranker | smart (Reflex) | Reranker that orders the pool: smart, lexical, rrf, none, or a full reranker name. See Rerankers. |
sort | Score, descending | { "by": "score" | "createdAt" | "updatedAt" | "indexedAt" | "name", "dir": "asc" | "desc" }. Without dir, score sorts descending and the other fields ascending. |
limit | 10 | Results per page, from 1 to 128. |
cursor | — | page.cursor from the previous response, to read the next page. |
include | content, metadata | Optional document fields: content, metadata, and references. references attaches the other documents that share the reference of each result. |
Sorting and reranking #
Use this table when you need to know whether a reranker runs. A reranker orders by relevance, so it only applies when results are sorted by score:
| Request | Behavior |
|---|---|
No sort and no reranker | Reflex reranks the pool; results are sorted by score. |
reranker without sort | That reranker reranks the pool; results are sorted by score. |
sort other than score, without reranker | Reranking is disabled. The pool is selected by similarity and then sorted by the requested field. |
sort other than score with reranker: "none" | Same as above. |
sort other than score with any other reranker | Rejected with 400 Bad Request. |
To get the most recent relevant documents, select a pool by meaning and sort it by date:
{
"collections": [ "<collection-id>" ],
"terms": "pricing change",
"candidates": 100,
"sort": { "by": "createdAt", "dir": "desc" }
}Each reranker has a maximum number of documents it accepts; a candidates value above it is rejected.
Results #
Each result tells you which document matched and how it scored. It has a rank, a document, and scores:
documentcontainsid,collectionId,name,reference,tags,createdAt,updatedAt,indexedAt, and the fields requested ininclude.scores.similarityis the vector similarity,scores.rerankis the reranker score (ornull), andscores.finalis the rerank score when a reranker ran, otherwise the similarity.
The response also contains page.cursor, page.hasMore, page.candidates (the size of the pool), and the reranker that ran.
Pages #
Use a cursor when the first page is not enough and you want the next slice of the same pool.
- The first request computes the candidate pool and returns its first page.
- To read the next page, send the same request body with
cursorset to the previouspage.cursor. - Later pages are read from the stored pool, so they are not charged again and keep the same order.
A cursor expires after 10 minutes without use and then returns 410 Gone. Repeat the request without cursor to run the query again. A cursor sent with a different request body is rejected with 400 Bad Request. The pool never grows. To see more than candidates results, raise candidates.
Find similar documents #
Use this endpoint for a “more like this” feature. It searches with the stored vector of an indexed document you already have.
The source document is never returned. The request accepts documentId and the same collections, filter, minScore, candidates, sort, limit, cursor, and include options as a query. Without collections, it searches the collection of the source document.
{
"documentId": "<document-id>",
"limit": 5
}Nothing is embedded or reranked.
scores.rerankis alwaysnull.- The source document must be indexed.
- A document still waiting for indexing is rejected with
400 Bad Request.
Browse documents #
Use this endpoint to list indexed documents in a fixed order, without ranking by meaning.
By default, documents are returned in insertion order, oldest first. Without a filter, every indexed document of the collections is listed.
{
"collections": [ "<collection-id>" ],
"filter": "createdAt >= now-7d",
"sort": { "by": "createdAt", "dir": "desc" },
"limit": 50
}It accepts collections, filter, sort, limit, cursor, and include.
sort.bycan becreatedAt,updatedAt,indexedAt, orname.- Sorting by score is rejected.
- Results contain only
document, withoutrankorscores.
Browse cursors point to the last returned document instead of a stored pool, so they do not expire. Documents added or changed between requests appear in later pages according to the sort order.
Filter results #
Filters narrow the documents a search can return, using exact conditions on document fields rather than semantic similarity. Use them when the answer must come from a known subset, such as one product, tenant, language, document type, or period.
| Filter on | Example | Use for |
|---|---|---|
| Name | name startswith "policy-" | Document families that follow a naming convention. |
| Tags | tags has "finance" | Operational labels assigned on import. |
| Metadata | metadata.region = "br" | Structured values stored with each document, such as region, version, or author. |
| Contents | content contains "refund" | Required words or identifiers in the text. |
| Dates | updatedAt >= now-30d | Recently created or updated documents. |
How filters combine:
- Combine conditions with
and,or,not, and parentheses, for exampletags has "finance" and createdAt >= now-30d. - When
filteris a list, every expression must match. - A filter set on a collection item is combined with the top-level
filterfor that collection. - Filters run before the search terms are embedded.
- Only matching documents are ranked, so results never include documents outside the filter.
- When no document matches, a query returns an empty result without generating embeddings or charging for the query.
Filters do not replace good document text. The meaning a user searches for must appear in the contents. See Advanced filters for the complete syntax, operators, limits, and errors, or How to filter RAG results by metadata, tags and date for a worked guide.
Multiple terms #
Use multiple terms for synonyms, alternative phrasings, or several acceptable ways to find an answer. They cover alternative retrieval paths. They do not require every term to match the same document. Each document is scored by its best match among the terms.
If the user’s question combines several related conditions, keep them together in one search term. Prefer:
How do I cancel an annual subscription without a penalty?Do not split that question into disconnected keywords:
cancellation
annual subscription
penaltyA complete query usually performs better than a list of disconnected keywords because it preserves the relationship between concepts. If users search by product codes, policy IDs, plan names, or procedure names, include those identifiers in the document text.
Reranking #
Use a reranker when vector search already returned a candidate pool and you want a more relevant order. It adjusts that order. It does not search additional documents or recover text that the retrieval stage did not select. Raise candidates to give it more documents. See Rerankers for selection guidance.
Errors #
Use this table to match a failed search to the next action.
| Status | Cause |
|---|---|
400 Bad Request | Invalid field, unknown collection or document, invalid filter, a reranker combined with a sort other than score, or a cursor sent with a different request body. |
410 Gone | The query cursor expired. Repeat the request without cursor. |
429 Too Many Requests | The plan’s search or reranking rate limit was exceeded. |
Search quality #
Use this checklist when search returns poor results:
- Confirm that the documents are indexed.
- Query the collection directly before testing through an AI Gateway.
- Compare complete questions with alternative phrasings.
- Check whether the relevant document is too short, too long, or not self-contained; see Write good documents.
- Check whether the query language matches the document language.
- If the gateway rewrites questions before searching, test with the plain query path to isolate rewriting issues.
- Review low-scoring searches and query coverage in RAG Observability.
To expose collections as tools for an external MCP client, see Collections and RAG MCP. For search pricing and rate limits, see Collections.
