AIVAX

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:

EndpointPathUse it toCost
Query collectionsPOST /api/v2/queryFind the documents that best answer a question.Query embedding and, when used, reranking.
Find similar documentsPOST /api/v2/query/similarFind documents close in meaning to a document you already have.No embedding or reranking cost.
Browse documentsPOST /api/v2/query/browseList 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:

  1. Add documents to a collection.
  2. Wait for indexing. Only indexed documents are returned.
  3. 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:

  1. If a filter is set, AIVAX restricts each collection to the documents that match it.
  2. Each search term is embedded and compared with the remaining documents.
  3. Documents below minScore are discarded, and the closest candidates documents form the candidate pool.
  4. The reranker reorders the pool, unless reranking is disabled.
  5. The pool is sorted and returned in pages of limit results.
JSON
{
  "collections": [ "<collection-id>" ],
  "terms": "How do I request a refund?"
}

Use these options to narrow the corpus, size the pool, and page the results.

OptionDefaultDescription
collectionsRequiredCollection IDs owned by the account. An item can also be { "id": "<collection-id>", "filter": "..." } to filter only that collection.
termsRequiredOne search text or a list of alternative texts.
filter—An advanced filter expression, or a list of expressions that must all match.
minScore0.2Minimum 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.
candidateslimit × 3Size of the candidate pool, from limit to 1000. A larger pool gives the reranker and later pages more documents to work with.
rerankersmart (Reflex)Reranker that orders the pool: smart, lexical, rrf, none, or a full reranker name. See Rerankers.
sortScore, descending{ "by": "score" | "createdAt" | "updatedAt" | "indexedAt" | "name", "dir": "asc" | "desc" }. Without dir, score sorts descending and the other fields ascending.
limit10Results per page, from 1 to 128.
cursor—page.cursor from the previous response, to read the next page.
includecontent, metadataOptional 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:

RequestBehavior
No sort and no rerankerReflex reranks the pool; results are sorted by score.
reranker without sortThat reranker reranks the pool; results are sorted by score.
sort other than score, without rerankerReranking 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 rerankerRejected with 400 Bad Request.

To get the most recent relevant documents, select a pool by meaning and sort it by date:

JSON
{
  "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:

  • document contains id, collectionId, name, reference, tags, createdAt, updatedAt, indexedAt, and the fields requested in include.
  • scores.similarity is the vector similarity, scores.rerank is the reranker score (or null), and scores.final is 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.

  1. The first request computes the candidate pool and returns its first page.
  2. To read the next page, send the same request body with cursor set to the previous page.cursor.
  3. 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.

JSON
{
  "documentId": "<document-id>",
  "limit": 5
}

Nothing is embedded or reranked.

  • scores.rerank is always null.
  • 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.

JSON
{
  "collections": [ "<collection-id>" ],
  "filter": "createdAt >= now-7d",
  "sort": { "by": "createdAt", "dir": "desc" },
  "limit": 50
}

It accepts collections, filter, sort, limit, cursor, and include.

  • sort.by can be createdAt, updatedAt, indexedAt, or name.
  • Sorting by score is rejected.
  • Results contain only document, without rank or scores.

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 onExampleUse for
Namename startswith "policy-"Document families that follow a naming convention.
Tagstags has "finance"Operational labels assigned on import.
Metadatametadata.region = "br"Structured values stored with each document, such as region, version, or author.
Contentscontent contains "refund"Required words or identifiers in the text.
DatesupdatedAt >= now-30dRecently created or updated documents.

How filters combine:

  • Combine conditions with and, or, not, and parentheses, for example tags has "finance" and createdAt >= now-30d.
  • When filter is a list, every expression must match.
  • A filter set on a collection item is combined with the top-level filter for 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:

TEXT
How do I cancel an annual subscription without a penalty?

Do not split that question into disconnected keywords:

TEXT
cancellation
annual subscription
penalty

A 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.

StatusCause
400 Bad RequestInvalid 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 GoneThe query cursor expired. Repeat the request without cursor.
429 Too Many RequestsThe plan’s search or reranking rate limit was exceeded.

Search quality #

Use this checklist when 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; see Write good documents.
  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.
  7. 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.

Type to search the documentation.