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 optional reasoning field and reasoning_delta stream event are a 0.48 addition. The charged amount on the done event (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:

  • 402 means the balance is short (or the monthly allowance or the plan is exceeded): top up or upgrade.
  • 429 with errorCode BALANCE_BUSY means 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 the Retry-After header. A 429 without that code is the burst rate limit.
  • 503 with errorCode BALANCE_UNAVAILABLE means a temporary service fault interrupted the balance step. It is not a shortage either: do not top up; retry after the seconds in Retry-After.
  • On RAG, a 503 without an errorCode means search.requireComplete was set and a retrieval leg was unavailable, or (with providerAlias) the stored provider key could not be opened. Branch on errorCode to tell the two apart.
  • On a call with providerAlias, 403 carries an errorCode when the waiver is not in force (WAIVER_NOT_SIGNED, WAIVER_TEXT_CHANGED when the version in force is older than the one Vectros requires, or WAIVER_REVOKED), and a 503 without an errorCode means 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, and uniqueDocuments / minSimilarity knobs. (The MCP tool defaults lower than the API — default 3, max 50 — to protect the agent's context window; paginate with offset for 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 — raise limit for a broader single grounding pass, don't expect an offset.) It takes an optional providerAlias to 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_search and record_query default to 3, rag_ask retrieval to 5; the API defaults are 10–100). This protects the agent's context window — it is not a bug. Raise each tool's limit when an agent needs wider recall — the MCP max is 50 for hybrid_search and rag_ask retrieval, 100 for record_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 optional providerAlias.

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.