Skip to main content
@vrin/sdk is the official TypeScript client. It works in Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers. Written in TypeScript, shipped as both ESM and CJS, fully typed. If you’re building an agent in Python, use the Python SDK. If you’re shell-scripting, use the CLI.

​
Install

npm install @vrin/sdk
Also works with pnpm add, yarn add, bun add.

​
Authenticate

import { VrinClient } from "@vrin/sdk";

const client = new VrinClient({ apiKey: process.env.VRIN_API_KEY });
The API key starts with vrin_live_ (shared infra) or vrin_ent_ (enterprise-routed). Get one at vrin.cloud → Dashboard → API Keys. If apiKey is omitted, the client reads VRIN_API_KEY from process.env.

​
First query

const result = await client.query({ query: "What is ACME's Q4 revenue?" });
console.log(result.summary);
for (const source of result.sources) {
  console.log(` - ${source.title}`);
}

​
Constructor options

OptionTypeDefaultDescription
apiKeystringprocess.env.VRIN_API_KEYVrin API key.
baseUrlstringhttps://api.vrin.cloudOverride for staging or self-hosted deployments.
timeoutMsnumber120000Per-request timeout. Must be ≥ the slowest query you expect.
maxRetriesnumber2Retry count for transient 5xx/network failures.
fetchtypeof fetchglobal fetchInject a custom fetch for runtimes that don’t have one (Node < 18, some edge environments).

​
Usage across runtimes

import { VrinClient } from "@vrin/sdk";
const client = new VrinClient({ apiKey: process.env.VRIN_API_KEY });

​
Next steps

Querying

query, queryStream, response modes, depth.

Knowledge

insert, uploadFile, polling async jobs.

Conversations

Multi-turn sessions with startConversation + continueConversation.

Error handling

Typed exception hierarchy you can switch on.

​
Error handling

All errors extend VrinError. Import the specific subclasses you want to handle: 
import {
  VrinClient,
  VrinError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  ServiceUnavailableError,
  TimeoutError,
  InsufficientCoverageError,
} from "@vrin/sdk";

try {
  const r = await client.query({ query: "..." });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // bad key — prompt the user to re-auth
  } else if (err instanceof RateLimitError) {
    // back off; err.retryAfterSeconds is populated if the server sent a Retry-After header
    await sleep((err.retryAfterSeconds ?? 1) * 1000);
  } else if (err instanceof InsufficientCoverageError) {
    // knowledge base has no relevant facts — ingest more or broaden the query
  } else if (err instanceof TimeoutError) {
    // request exceeded timeoutMs — retry with a longer timeout or split the query
  } else if (err instanceof VrinError) {
    console.error("Vrin error:", err.status, err.message);
  } else {
    throw err;
  }
}
VrinError exposes:
  • message — human-readable description
  • status? — HTTP status, when relevant
  • body? — raw server payload, for logging

​
Custom fetch

For runtimes without a global fetch (Node 16, some embedded envs) or when you want a middleware-style interceptor: 
import { VrinClient } from "@vrin/sdk";
import { fetch as undiciFetch } from "undici";

const client = new VrinClient({
  apiKey: process.env.VRIN_API_KEY,
  fetch: undiciFetch as unknown as typeof fetch,
});