@qverisai/sdk

TypeScript SDK for QVeris — the Agent External Data & Tool Harness. Discover, inspect and call 1000+ ranked external data & tool capabilities with unified billing and usage audit. No per-provider API keys required.

• Typed end to end — response types aligned with the public OpenAPI contract (categories, capabilities, why_recommended, expected_cost, billing)
• Zero dependencies — native fetch, Node.js 18+
• Same wire semantics as the Python SDK and the MCP server

Install#

npm install @qverisai/sdk

Quickstart#

import { Qveris } from '@qverisai/sdk';
 
const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });
// or: const qveris = Qveris.fromEnv();
 
// 1. Discover — free, returns ranked capabilities
const found = await qveris.discover('stock price market data API', { limit: 5 });
for (const tool of found.results) {
  console.log(tool.tool_id, '—', tool.why_recommended);
}
 
// 2. Inspect — free, current parameter schemas
const detail = await qveris.inspect(found.results[0].tool_id, {
  searchId: found.search_id,
});
 
// 3. Probe — zero-cost validation and quote; no capability execution
const probe = await qveris.probe(found.results[0].tool_id, {
  parameters: { symbol: 'AAPL' },
  checks: ['schema', 'quote'],
});
 
// 4. Call — billed in credits; response includes pre-settlement billing
const outcome = await qveris.call(found.results[0].tool_id, {
  searchId: found.search_id,
  parameters: { symbol: 'AAPL' },
});
console.log(outcome.success, outcome.result);

Audit#

// Final charge status for an execution
const usage = await qveris.usage({ execution_id: outcome.execution_id });
 
// Credit balance movements
const ledger = await qveris.ledger({ direction: 'consume', summary: true });
 
// Current balance
const credits = await qveris.credits();

API reference#

Construct with new Qveris({ apiKey }) or Qveris.fromEnv(overrides?) (reads QVERIS_API_KEY and resolves the API endpoint automatically). Applications that manage short-lived credentials can instead pass an async-capable provider:

import { Qveris, type CredentialProvider } from '@qverisai/sdk';
 
const credentialProvider: CredentialProvider = {
  async getCredential({ resource, scopes }) {
    // Resolve a bearer credential through your application's credential store.
    return process.env.QVERIS_API_KEY!;
  },
};
 
const qveris = new Qveris({ credentialProvider });

The provider receives the resolved API resource and the requested scopes (currently empty). Configure either apiKey or credentialProvider, never both. A provider does not select or change the API endpoint.

A credential provider supplies the bearer value that authenticates requests to the QVeris API itself. It is unrelated to the data and tool providers in the capability catalog: their upstream credentials are managed by the platform and never pass through the SDK.

Read-only members: qveris.rateLimitRetryCount (see Rate limiting).

Key response fields:

• SearchResponse — search_id, total, results: ToolInfo[] (tool_id, name, description, params, examples.sample_parameters, stats.success_rate, stats.avg_execution_time_ms, expected_cost, why_recommended).
• ExecuteResponse — execution_id, success, result, billing (pre-settlement estimate; the final charge is in usage() / ledger()).

Projection options are never sent unless explicitly configured. If a legacy service returns 422 extra_forbidden for an optional projection field, the SDK retries once without that field; validation errors for an invalid projection are returned unchanged.

All types are exported from the package root (import type { SearchResponse, ExecuteResponse, ToolInfo } from '@qverisai/sdk').

Configuration#

API keys never select the endpoint. Endpoint overrides must be HTTP(S) URLs without credentials, a query string, or a fragment.

Rate limiting & retries#

The client transparently retries rate-limited (429) and transient (503) responses: it honors the Retry-After header when present, otherwise backs off exponentially with full jitter. Each wait is capped and retries are bounded by maxRetries, so a call never hangs.

const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY!, maxRetries: 5 });
// ... after some calls under load:
qveris.rateLimitRetryCount; // how many times it backed off (pressure, not failures)

Set maxRetries: 0 to disable. Rate-limit backoff is retried pressure rather than failure — read rateLimitRetryCount to observe it instead of treating the retried 429s as errors.

Errors#

All failures throw QverisApiError (an Error subclass) with status, details, and an observability object (operation, endpoint, request id) for diagnostics:

import { QverisApiError } from '@qverisai/sdk';
 
try {
  await qveris.call('some.tool.v1', { parameters: {} });
} catch (err) {
  if (err instanceof QverisApiError && err.status === 402) {
    // insufficient credits — err.message includes the purchase link
  }
}

Framework integrations#

Expose the QVeris workflow as Vercel AI SDK tools. ai and zod are peer dependencies:

npm install @qverisai/sdk ai zod

import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { Qveris } from '@qverisai/sdk';
import { getQverisTools } from '@qverisai/sdk/ai';
 
const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });
const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: getQverisTools(qveris), // qveris_discover / qveris_inspect / qveris_call
  stopWhen: stepCountIs(6),
  prompt: 'Find a stock quote capability and quote AAPL.',
});

Examples#

Runnable scripts in examples/: the discover → inspect → call quickstart, a Vercel AI SDK agent, and rate-limit/observability. Each is safe to run without an API key (it explains how to set one), and any credit-spending call is gated behind RUN_QVERIS_CALLS=1.

Version history note#

Versions 0.1.x of this npm package were an early MCP-focused SDK, since superseded by @qverisai/mcp. The typed REST client documented here starts at 0.2.0.

Related#

• QVeris CLI — qveris discover / inspect / call / usage / ledger
• QVeris MCP server — for Claude, Cursor and other MCP clients
• Python SDK
• REST API docs

License#

MIT