The Rivano SDK is a typed TypeScript client for the Rivano API. Use it to manage agents, query traces, configure policies, and automate governance from your application or scripts.

Installation

npm install @rivano/sdk
# yarn add @rivano/sdk
# pnpm add @rivano/sdk

Requires Node.js 18 or later.

Initializing the client

import Rivano from '@rivano/sdk';

const rivano = new Rivano({
  apiKey: process.env.RIVANO_API_KEY!,
});

import requests

BASE_URL = "https://api.rivano.ai/api"
HEADERS = {"Authorization": f"Bearer {os.environ['RIVANO_API_KEY']}"}

response = requests.get(f"{BASE_URL}/agents", headers=HEADERS)
data = response.json()

curl https://api.rivano.ai/api/agents \
  -H "Authorization: Bearer rv_..."

Configuration options

Option	Type	Description	Default
`apiKey`	`string`	Your Rivano API key	Required
`baseUrl`	`string`	API base URL	`https://api.rivano.ai`
`timeout`	`number`	Request timeout in milliseconds	`30000`
`retries`	`number`	Retry attempts on transient errors (429, 5xx)	`2`

import Rivano from '@rivano/sdk';

const rivano = new Rivano({
  apiKey: process.env.RIVANO_API_KEY!,
  baseUrl: 'https://api.rivano.ai',
  timeout: 15000,
  retries: 3,
});

Error handling

The SDK throws typed error classes. Catch the specific class you care about, or catch SdkError as a base:

import Rivano, {
  SdkError,
  SdkAuthError,
  SdkForbiddenError,
  SdkNotFoundError,
  SdkRateLimitError,
} from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

try {
  const agent = await rivano.agents.get('nonexistent-agent');
} catch (error) {
  if (error instanceof SdkNotFoundError) {
    console.error('Agent not found');
  } else if (error instanceof SdkRateLimitError) {
    console.error('Rate limited — back off and retry');
  } else if (error instanceof SdkAuthError) {
    console.error('Invalid API key');
  } else if (error instanceof SdkError) {
    console.error('API error:', error.message, error.statusCode);
  } else {
    throw error;
  }
}

Error classes

Class	HTTP Status	When it’s thrown
`SdkAuthError`	401	Invalid or missing API key
`SdkForbiddenError`	403	Valid key but insufficient permissions
`SdkNotFoundError`	404	Resource does not exist
`SdkRateLimitError`	429	Too many requests
`SdkError`	Any	Base class for all SDK errors

💡

The SDK retries 429 and 5xx responses automatically, up to the retries count. You only see SdkRateLimitError if all retries are exhausted.

Pagination

List methods return a ListResponse<T> object with data (the current page) and total (total matching records):

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const result = await rivano.traces.list({
  agentId: 'agent_abc123',
  limit: 50,
  offset: 0,
});

console.log(`${result.data.length} of ${result.total} traces`);

for (const trace of result.data) {
  console.log(trace.id, trace.status, trace.durationMs);
}

TypeScript types

All SDK methods return fully typed responses. Key types:

// Agent
interface Agent {
  id: string;
  name: string;
  description?: string;
  modelProvider?: string;
  modelName?: string;
  environment?: string;
  configYaml?: string;
  createdAt: string;
  updatedAt: string;
}

// Trace
interface Trace {
  id: string;
  agentId?: string;
  status: 'success' | 'error';
  environment?: string;
  sessionId?: string;
  durationMs: number;
  inputTokens: number;
  outputTokens: number;
  costUsd: number;
  createdAt: string;
}

// ListResponse
interface ListResponse<T> {
  data: T[];
  total: number;
}

SDK Agents — Manage agent deployments
SDK Traces — Query observability data
SDK Policies — Configure governance rules
API Reference — Raw REST endpoints

SDK Overview