Search & RAG — how-to guides
Goal-oriented, runnable guides for searching your content and getting grounded answers from a model. Every snippet here uses real SDK calls that pass against a live Vectros environment. All data is synthetic — fictional names and values only.
SDK version. These guides use the Node SDK. The API spec is at
0.50.0; anything that needs a newer client is marked inline. Nothing on this page requires 0.26 — every first-party client is well past that line today regardless. The optional global-region inference flag (allowGlobalRegion, below) is a 0.27 addition, and the optionalreasoningfield andreasoning_deltastream event are a 0.48 addition. The charged amount on thedoneevent (inferenceBalanceCentsChargedMilli, in milli-cents) needs a 0.49 client.
Client setup
All guides assume a constructed client. The constructor takes a token and an environment (the API base URL):
import { VectrosClient } from '@vectros-ai/sdk';
const client = new VectrosClient({
token: process.env.VECTROS_API_KEY!, // sk_*, ssk_*, or st_*
environment: process.env.VECTROS_API_BASE_URL!, // e.g. https://api.vectros.ai
});
Sub-clients are grouped by area: client.search.*, client.inference.*,
client.documents.*, client.records.*, client.schemas.*, client.folders.*.
A note on indexing latency. Writes are indexed asynchronously — a document or record is
not searchable the instant the write call returns. In application code you typically do not
wait; you write, and the content becomes searchable shortly after. In tests and demos, poll
until the content surfaces (search by a unique marker phrase, or scope retrieval with
createdAfter to your run's start time) rather than sleeping a fixed interval.
Search your content with hybrid mode and filters
Goal: find content across documents and records, then narrow with filters and read the results.
Prerequisites: a key with search:r; some indexed content. A scoped token additionally needs
the read grant for what it searches — documents:r and/or records:r, each optionally narrowed to
one type (documents:r:<type>, records:r:<type>) — since results are limited to content the token
could read directly (see "Scoping … with a scoped token" below).
Steps
A unified hybrid search — the default mode, querying both documents and records:
const results = await client.search.content({
query: 'lifestyle changes for stage 1 hypertension',
mode: 'HYBRID', // 'TEXT' | 'SEMANTIC' | 'HYBRID' (default HYBRID)
limit: 10,
});
for (const hit of results.results ?? []) {
console.log(hit.sourceType, hit.documentId, hit.score);
console.log('matched chunk:', hit.chunkText);
console.log('grounding context:', hit.contextText);
}
console.log(`${results.totalResults} total, ${results.searchTimeMs} ms`);
Each hit carries a sourceType discriminator — branch on it to tell a document hit from a
record hit (the literal values the API returns are the strings "PartnerDocument" and
"GenericRecord") — the source documentId (use it with getDocument / getRecord), an
externalId (your own id, when the item was ingested with one), the fused
score, the matched chunkText, the wider contextText, a highlighted snippet, and the
metadata supplied at ingest time. Check results.hasMore to know whether another page is
available — totalResults is only an approximate pool size, not a paging signal.
Narrow to one content type with contentTypes:
// Documents only
const docsOnly = await client.search.content({
query: 'ACE inhibitor dosing',
mode: 'HYBRID',
contentTypes: ['documents'],
});
// Records only
const recordsOnly = await client.search.content({
query: 'ACE inhibitor dosing',
mode: 'HYBRID',
contentTypes: ['records'],
});
Narrow records to one schema type with typeName (this implicitly restricts to records):
const patientRecords = await client.search.content({
query: 'follow-up scheduled',
mode: 'TEXT',
typeName: 'patient_visit', // only records of this schema type
limit: 50,
});
Scope to a folder (exact folder), or to a folder and all its descendants:
const inFolder = await client.search.content({
query: 'intake notes',
mode: 'HYBRID',
folderId: '<folder-uuid>', // this exact folder only
// rootFolderId: '<folder-uuid>', // this folder AND all descendants
});
Filter by ownership (user / org / client) and by metadata fields:
const scoped = await client.search.content({
query: 'medication review',
mode: 'HYBRID',
scope: 'client:<client-uuid>', // ownership scope — one <namespace>:<value> per call
filters: {
status: 'open', // equality
tag: ['anxiety', 'depression'], // OR-set: match any
visitCount: { $gte: 2, $lte: 10 }, // closed range
},
});
Filter values may be a scalar (equality), an array (match any), or an operator map
($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin). Metadata filter keys must be
fields declared filterable on the schema; you cannot use the filters map to inject a
tenancy or ownership key to widen your access — those are enforced separately.
Expected result: a results array plus totalResults, searchTimeMs, and the
degraded / degradedLegs fields. An empty result set for a query that matches nothing is
a normal 200 with results: [] and totalResults: 0 — not an error.
Paging search results
search.content is not wrapped in the cursor envelope that list and lookup endpoints
use — it has no nextCursor. Page with limit and offset instead:
const page1 = await client.search.content({ query, mode: 'TEXT', limit: 20, offset: 0 });
const page2 = await client.search.content({ query, mode: 'TEXT', limit: 20, offset: 20 });
limit is capped at 100 and offset at 200 (an offset above 200 is rejected with
400). Consecutive pages are disjoint. For pulling a known set of recent content
deterministically — or for reaching past the 200-row offset ceiling — prefer a
createdAfter window over deep offset paging.
Collapse multiple chunks of the same document
By default a search returns at most one hit per source document (uniqueDocuments is true).
To get chunk-level results instead, where a long document that matches on several of its chunks
produces several hits with the same documentId, set uniqueDocuments: false:
const chunks = await client.search.content({
query: 'hypertension monitoring',
mode: 'TEXT',
uniqueDocuments: false, // every matching chunk, not one hit per document
limit: 50,
});
Get a grounded answer over your whole corpus (RAG)
Goal: ask a natural-language question and stream back a model answer grounded on your indexed content, with citations.
Prerequisites: a key with inference:r (and search:r for the retrieval step); some
indexed content; a positive inference balance on balance-mode plans. A scoped token additionally
needs the read grant for the corpus it grounds on — documents:r and/or records:r, each
optionally narrowed to one type — since RAG grounds only on content the token could read directly
(see "Scoping RAG retrieval" below).
Steps
ragInference returns an async iterable of SSE events. The first informative event is
search_results (the citations), followed by content_delta events (the streamed answer),
ended by a single done event:
const stream = await client.inference.ragInference({
query: 'What treatment is recommended for stage 1 hypertension?',
model: 'claude-sonnet-5', // optional; omit for the platform default (`claude-haiku-5-5`)
search: {
mode: 'HYBRID',
limit: 5, // retrieval topK (default 10, valid range 1–100; outside it is a 400)
// narrow retrieval the same way you narrow search:
// scope ('org:<id>' / 'client:<id>' / '<namespace>:<id>'), userId, folderId, typeName, createdAfter, createdBefore
},
maxTokens: 1024, // capped at 4096 for RAG
});
let answer = '';
let citations: Array<{ documentId: string; chunkText?: string }> = [];
for await (const event of stream) {
switch (event.event) {
case 'search_results':
citations = event.results; // show these so the user can verify grounding
// event.hasMore is true when more matching results may exist than were retrieved —
// raise search.limit (max 100) or narrow your filters.
break;
case 'truncation_warning':
// some retrieved passages were dropped to fit the context budget
console.warn('grounding truncated:', event.reason);
break;
case 'content_delta':
answer += event.delta; // append each chunk
break;
case 'done':
console.log('tokens:', event.inputTokens, '→', event.outputTokens);
console.log('charged:', event.inferenceBalanceCentsChargedMilli / 1000, 'cents'); // the field is in milli-cents
break;
case 'error':
throw new Error(event.message);
}
}
Each entry in search_results.results carries documentId, externalId, score,
chunkText, contextText, snippet, metadata, sourceType, typeName, and createdAt
— the same shape as a search hit, so you can render the citations exactly as you would
render search results. UIs typically show the citations above the answer so the user can
verify the grounding while the model is still generating.
query and instructions count toward the request-body limit of 8 KB (413). Put large context in your indexed content
and let retrieval bring it in, rather than pasting it into these fields.
If retrieval finds nothing, the search_results event still fires (with an empty
results array) and the model still answers — typically stating that it found no relevant
content. The contract is that search_results is always emitted, even when empty.
Refuse a partial answer. If you would rather fail than ground on a degraded retrieval,
set search.requireComplete: true. The call then returns an error before the stream
opens when a search leg is unavailable, instead of grounding on partial results.
Expected result: the assembled answer string, a citations array you can display,
and a per-call cost on the done event.
Scoping RAG retrieval with a scoped token
A scoped token's data scope is enforced on the retrieval step, so RAG over a scoped token
only grounds on content that token is allowed to read. Retrieval is enforced per result
against what the token could read directly, so the token needs the read grant for the
content it grounds on — documents:r (or documents:r:<type> for a single document type)
to ground on documents, records:r (or records:r:<type> for a single record type) to
ground on records — in addition to
inference:r. search:r/inference:r alone ground on nothing. Mint a token scoped to a
user and RAG through it:
const minted = await client.auth.mintToken({
userId: '<user-uuid>',
scope: {
// inference:r to call RAG; documents:r (and/or records:r) grants the retrieval read.
allowedActions: ['inference:r', 'search:r', 'documents:r'],
dataScope: { userId: ['<user-uuid>'] },
},
});
const scoped = new VectrosClient({
token: minted.token,
environment: process.env.VECTROS_API_BASE_URL!,
});
const stream = await scoped.inference.ragInference({
query: 'What treatments are discussed?',
search: { mode: 'HYBRID', limit: 10, userId: '<user-uuid>' },
maxTokens: 1024,
});
Because the data scope lists a single userId with no null sentinel, every call must
include the matching userId. To also reach tenant-level (owner-less) content under the
same token, include null in the scope list: dataScope: { userId: ['<user-uuid>', null] }.
Ask a single document
Goal: ask one question about one specific document and stream the answer.
Prerequisites: a key with inference:r (to run the model) and documents:r (to read the
document's content); the document's id; the document indexed with its text stored. A scoped token
must hold documents:r for the document it asks about (or documents:r:<type> matching the document's
type), within its data scope — inference:r alone
authorizes running inference, not reading document content, so a token with inference:r but no
documents:r gets a 404 (the same not-found response used for a document outside your scope).
Steps
documentAsk takes the document id and a prompt in the request body. It streams a
document_context event first (the document it loaded), then the answer:
const stream = await client.inference.documentAsk({
id: '<document-uuid>',
prompt: 'Which medications does this document describe, and how do they work?',
model: 'claude-haiku-4-5', // optional; omit for the platform default (`claude-haiku-5-5`)
maxTokens: 1024, // output cap 8192
});
let answer = '';
for await (const event of stream) {
switch (event.event) {
case 'document_context':
console.log('asking against:', event.documentId, event.title, `${event.textBytes} bytes`);
break;
case 'content_delta':
answer += event.delta;
break;
case 'done':
console.log('charged:', event.inferenceBalanceCentsChargedMilli / 1000, 'cents'); // the field is in milli-cents
break;
}
}
Handle the oversize case. A document larger than the input cap (~25 pages, 32,000
estimated input tokens) is rejected with a 413 before the stream opens — and before
any credits are charged. The error payload carries estimatedTokens and limitTokens so
you can branch and re-route to RAG:
try {
const stream = await client.inference.documentAsk({ id, prompt, maxTokens: 1024 });
// ... consume stream
} catch (err: any) {
if (err.statusCode === 413) {
// too large for single-document ask — use corpus RAG instead
return askViaRag(prompt);
}
throw err;
}
A not-yet-ready document returns 409. A document that is not yet fully indexed, that
failed ingest, that has no extractable text (check its extraction), or that was ingested without its text stored returns a 409 before the
stream opens. Asking a document the instant after you ingest it commonly hits this — wait for
indexing to complete, and ingest with the text stored if you intend to ask against it.
Out-of-scope and missing documents both return 404. Asking about a document that does
not exist, that belongs to another tenant, or that your token's scope cannot see all return
the same 404 — the endpoint never reveals whether a document exists outside your scope.
Expected result: a streamed answer grounded on that one document, or a structured
413 (too large) or 404 (not visible to you).
Make a stateless chat call
Goal: a single-turn model completion you manage the context for yourself.
Prerequisites: a key with inference:r; a positive inference balance on balance-mode
plans.
Steps
chatInference takes a messages array. A system message sets the system prompt; the
rest is passed through. It streams content_delta events then a done:
const stream = await client.inference.chatInference({
messages: [
{ role: 'system', content: 'You are a concise clinical scribe.' },
{ role: 'user', content: 'Summarize this visit note in three bullets: ...' },
],
model: 'claude-haiku-4-5', // optional
maxTokens: 512, // output cap 8192
});
let reply = '';
for await (const event of stream) {
if (event.event === 'content_delta') reply += event.delta;
if (event.event === 'done') {
console.log('model:', event.model);
console.log('tokens:', event.inputTokens, '→', event.outputTokens);
}
}
Multi-turn is your responsibility. Chat stores nothing. To carry a conversation,
append the model's reply to your messages array and re-send the whole array on the next
turn:
const history = [
{ role: 'user', content: 'My care plan emphasizes lifestyle changes.' },
{ role: 'assistant', content: 'Noted — lifestyle-first care plan.' },
{ role: 'user', content: 'What did I just say my care plan emphasized?' },
];
const stream = await client.inference.chatInference({ messages: history, maxTokens: 1024 });
Expected result: the streamed reply and a done event with token counts and the
resolved model id.
Stream the model's reasoning (optional)
Goal: receive the reasoning of a model that reasons before it answers, separately from the answer.
Prerequisites: SDK 0.48.0 or later; a call on chatInference, ragInference or documentAsk
to a platform-hosted model that reasons (see reference.md).
Steps
Set reasoning: 'stream' (the default is 'omit'). The reasoning arrives as reasoning_delta
events before the content_delta events of the answer; on RAG they follow search_results, and
on documentAsk they follow document_context:
const stream = await client.inference.chatInference({
messages: [{ role: 'user', content: 'Is 1,001 a prime number? Explain briefly.' }],
reasoning: 'stream',
maxTokens: 2048, // the reasoning counts against this, so leave headroom
});
let reasoning = '';
let reply = '';
for await (const event of stream) {
if (event.event === 'reasoning_delta') reasoning += event.delta; // not part of the answer
if (event.event === 'content_delta') reply += event.delta;
}
Expected result: reasoning holds the model's reasoning (empty for a model that does not
reason) and reply holds only the answer. Do not concatenate the two. The reasoning can quote
your documents or messages, so treat it as you treat the answer. It counts against maxTokens
and is billed as output whether or not you ask for it, so reasoning: 'stream' does not change
the cost of the call. A value other than 'omit' or 'stream' is rejected with 400, and a call
routed with providerAlias ignores the field.
Handle a call that is refused before the stream opens
A call can be refused with an HTTP error before any event is sent, and nothing is charged. The status tells you what to do:
402means the balance is short (or the monthly allowance or the plan is exceeded): top up or upgrade.429witherrorCodeBALANCE_BUSYmeans your pre-paid balance is momentarily busy with other concurrent requests of yours. It is not a shortage and not a rate-limit breach: do not top up; retry after the seconds in theRetry-Afterheader. A429without that code is the burst rate limit.503witherrorCodeBALANCE_UNAVAILABLEmeans a temporary service fault interrupted the balance step. It is not a shortage either: do not top up; retry after the seconds inRetry-After.- On RAG, a
503without anerrorCodemeanssearch.requireCompletewas set and a retrieval leg was unavailable, or (withproviderAlias) the stored provider key could not be opened. Branch onerrorCodeto tell the two apart. - On a call with
providerAlias,403carries anerrorCodewhen the waiver is not in force (WAIVER_NOT_SIGNED,WAIVER_TEXT_CHANGEDwhen the version in force is older than the one Vectros requires, orWAIVER_REVOKED), and a503without anerrorCodemeans the stored provider key could not be opened: retry shortly, and if it persists enter the key again in the developer portal.
The full table is in reference.md.
List the models your key can reach
Goal: discover which inference models exist and which plans can call each, before you call.
const catalog = await client.inference.listInferenceModels();
console.log('default model:', catalog.defaultModel);
for (const m of catalog.models) {
console.log(m.id, '— context window', m.contextWindow, '— plans:', m.availableOn);
}
Each entry carries the alias id (e.g. claude-haiku-4-5), a display name, the
provider, the contextWindow, per-1k-token credit rates (with regionPricing, and longContext and
cachePricing on a model that has them), and availableOn (the plan
tiers that may call it). defaultModel is what an inference call resolves to when you omit
model — it is available on every plan. It is claude-haiku-5-5.
Name claude-haiku-4-5 in model to use that model instead. Reaching a model is separate from paying for it: a
call on a balance-billed account still returns 402 until the inference balance is funded, and funding needs a paid plan
(developer portal, Usage → Inference balance).
Route a call to your own model provider
Goal: serve one chat, RAG, or document-ask call from a model provider you control instead of the platform-hosted models.
Prerequisites: a provider config your account owner has set up (a customer-supplied Anthropic key, or an OpenAI-compatible endpoint), its alias, and a risk-acceptance waiver on your account. If your account has accepted the Business Associate Agreement with Vectros in the developer portal, the config also needs a current attestation from an owner (below).
An account owner does this in the developer portal, under Model Providers, for each environment (live or test): add the provider (its alias, its endpoint, and its key, which is stored and never shown again), then read and sign the risk waiver. The waiver is shown formatted for reading, with a view of the exact text that is recorded when it is signed. The page shows each config's state and, when a config is not usable, the reason (for example, the waiver is not signed, or the version in force is older than the version Vectros requires). The owner can edit a config's alias, provider type, endpoint or default model, rotate a key, switch a config off, delete it, or revoke the waiver, after which routed calls are refused, normally within moments. Every routed call is billed by the provider directly.
If your account has accepted the Business Associate Agreement with Vectros in the developer portal, a routed call is a disclosure you direct, and your provider is not covered by that agreement. For each config, an owner attests in the developer portal (or the developer API) that the account holds its own agreement with the provider at that config's endpoint, covering the information it will send, and is permitted to direct the disclosure. The page shows, for each config, whether it is attested and when. Do this after you save the endpoint you intend to keep: changing the provider type or the endpoint, even by letter case or a trailing slash, withdraws the attestation in the same change, and routed calls through that config are refused until an owner attests again. After you save an edit, the page shows the state the server returns; check whether it still shows the config as attested (through the API, read the config back). The attestation applies to the test and live environments alike; each config needs its own.
Choose the alias with care: it is the providerAlias your callers send, and it must be 1 to 64
lowercase letters, digits, - or _. The match is exact and case-sensitive. Changing an alias
stops calls that still send the old one, so update those callers first or together. The endpoint is a plain https URL on port 443 without credentials, query or fragment; an endpoint on another
port is rejected with 400. Pointing a
config at an endpoint on a different host needs the provider key entered again. Changing a config's
provider type through the API or the CLI needs the endpoint stated in the same request (an empty
string means the provider's default); the portal does this for you. A config whose alias is outside
this rule keeps working under it.
const stream = await client.inference.chatInference({
providerAlias: 'my-provider', // the alias of your provider config
model: 'my-provider-model-id', // optional: the model on YOUR provider; falls back to the config's default
messages: [{ role: 'user', content: 'Summarize this visit note in three bullets: ...' }],
});
providerAlias works the same way on ragInference and documentAsk. When it is set,
model names a model on your provider (not a Vectros catalog alias); a call with no model and
no default model on the config is rejected with 400, and an unknown or inactive alias, a
missing waiver, or (on an account that has accepted the Business Associate Agreement with Vectros in the developer portal) a config
without a current attestation, with 403. allowGlobalRegion and your residency settings do not
apply. A call you route to your own provider is
processed where your provider processes it and leaves the Vectros perimeter. The provider bills you directly, so the call does
not draw your inference balance. See the
reference.
Drive search and RAG from an AI agent (MCP)
If you are building with an agent over the Model Context Protocol rather than calling the SDK directly, the Vectros MCP server exposes the same capabilities as tools:
hybrid_search— wraps content search. Same modes, filters, ownership scope, folder scope, anduniqueDocuments/minSimilarityknobs. (The MCP tool defaults lower than the API — default 3, max 50 — to protect the agent's context window; paginate withoffsetfor more.)rag_ask— wraps corpus RAG. The agent gets the assembled answer plus the citations and usage in one tool result; progress notifications keep the call alive during generation. (Its retrieval defaults to 5 results, max 50; retrieval doesn't page — raiselimitfor a broader single grounding pass, don't expect anoffset.) It takes an optionalproviderAliasto route the call through your own model provider; see the note below.
Why agent results can look sparse. The MCP tools deliberately default to far fewer results than the API (
hybrid_searchandrecord_querydefault to 3,rag_askretrieval to 5; the API defaults are 10–100). This protects the agent's context window — it is not a bug. Raise each tool'slimitwhen an agent needs wider recall — the MCP max is 50 forhybrid_searchandrag_askretrieval, 100 forrecord_query. The full per-tool cap table is in clients/mcp.md.
document_ask— wraps single-document Q&A, including the structured oversize signal. It also takes an optionalproviderAlias.
providerAlias on rag_ask and document_ask is passed through only when the caller supplies
it. It needs a provider config and a risk-acceptance waiver on your account (and, if your account
has accepted the Business Associate Agreement with Vectros in the developer portal, a current attestation on the config); without
them the platform refuses the call with a 403. A call routed this way is processed where your
provider processes it and leaves the Vectros perimeter.
The agent never sees content outside the scoped key the MCP server is configured with — the same scope enforcement applies. See the blueprint walkthroughs for the end-to-end no-code agent path.
Where to go next
- reference.md — every parameter, field, limit, and error code for search and the three inference surfaces.
- explanation.md — the concepts: why the three modes exist, grounding context, and how search and RAG are the same machinery.
- ../data-model/how-to.md — defining schemas with searchable and sensitive fields, and writing the records you search over.
- ../identity-access/how-to.md — minting scoped tokens and the data-scope / null-sentinel rules the RAG scoping example relies on.