SDK Reference

The Rivano SDK provides a thin client for interacting with the Rivano API, managing agents, and querying traces programmatically. If you only need proxy functionality, you don’t need the SDK — just point your AI client at the proxy endpoint (see Getting Started).

TypeScript SDK

Installation

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

Basic Usage

import { RivanoClient } from "@rivano/sdk";

const rivano = new RivanoClient({
  apiKey: process.env.RIVANO_API_KEY,
  baseUrl: "https://api.rivano.ai", // optional, defaults to production
});

// List all agents
const agents = await rivano.agents.list();

// Get traces for a specific agent
const traces = await rivano.traces.list({
  agentId: "agent_abc123",
  since: new Date(Date.now() - 24 * 60 * 60 * 1000), // last 24 hours
});

// Get cost summary
const costs = await rivano.costs.summary({
  agentId: "agent_abc123",
  period: "7d",
});

console.log(`Total spend: $${costs.totalCost.toFixed(4)}`);

Configuration Options

Option	Type	Default	Description
apiKey	string	—	Required. Your Rivano API key.
baseUrl	string	https://api.rivano.ai	API base URL. Override for self-hosted instances.
timeout	number	30000	Request timeout in milliseconds.
retries	number	2	Number of automatic retries on 5xx errors.
headers	Record<string, string>	{}	Additional headers sent with every request.
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation (useful for testing).

Error Handling

import { RivanoClient, RivanoError } from "@rivano/sdk";

try {
  const agent = await rivano.agents.get("agent_invalid");
} catch (err) {
  if (err instanceof RivanoError) {
    console.error(`API error ${err.status}: ${err.message}`);
    console.error("Request ID:", err.requestId); // useful for support
  }
  throw err;
}

TypeScript Types

The SDK exports full TypeScript types for all API resources:

import type { Agent, Trace, Policy, CostSummary } from "@rivano/sdk";

Python SDK

Installation

pip install rivano

Basic Usage

from rivano import RivanoClient

client = RivanoClient(api_key="your-api-key")

# List agents
agents = client.agents.list()
for agent in agents:
    print(f"{agent.name} ({agent.id})")

# Query traces with filters
traces = client.traces.list(
    agent_id="agent_abc123",
    since="2025-01-01T00:00:00Z",
    limit=100,
)

# Get cost breakdown
costs = client.costs.summary(agent_id="agent_abc123", period="30d")
print(f"Total: ${costs.total_cost:.4f}")
print(f"By model: {costs.by_model}")

Async Support

from rivano import AsyncRivanoClient

client = AsyncRivanoClient(api_key="your-api-key")

agents = await client.agents.list()
traces = await client.traces.list(agent_id="agent_abc123")

Configuration Options

Option	Type	Default	Description
api_key	str	—	Required. Your Rivano API key.
base_url	str	https://api.rivano.ai	API base URL.
timeout	float	30.0	Request timeout in seconds.
max_retries	int	2	Automatic retries on server errors.
http_client	httpx.Client	None	Custom HTTP client instance.

Rate Limits

All SDK methods respect Rivano’s API rate limits. When a rate limit is hit, the SDK automatically waits and retries (up to the configured retry count). Current limits:

Tier	Requests/min	Burst
Free	60	10
Pro	600	50
Team	3,000	200
Enterprise	Custom	Custom