The Rivano REST API gives you programmatic access to everything in the dashboard — agents, policies, traces, costs, teams, providers, and API keys.

Base URL

https://api.rivano.ai

All endpoints are prefixed with /api. Example: https://api.rivano.ai/api/agents.

Authentication

Every request requires a valid API key in the Authorization header:

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

API keys are prefixed with rv_ followed by the scope: rv_api_..., rv_agent_..., rv_ingest_....

Key scope	Access
`api`	Full read/write access to all control plane resources
`agent`	Read-only: agents and traces
`ingest`	Write: proxy trace data; used by the gateway

Create keys in the dashboard under Settings → API Keys or via the Keys API.

⚠

Use ingest-scoped keys for the gateway. Use api-scoped keys only for admin automation. Never embed api-scoped keys in client-side code.

Pagination

List endpoints accept limit and offset query parameters. Responses always include total:

GET /api/traces?limit=50&offset=100

{
  "data": [...],
  "total": 1247,
  "limit": 50,
  "offset": 100
}

Default limit is 50. Maximum limit is 500. To page through all results:

let offset = 0;
const limit = 500;
let all = [];

while (true) {
  const res = await fetch(`https://api.rivano.ai/api/traces?limit=${limit}&offset=${offset}`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  const { data, total } = await res.json();
  all = all.concat(data);
  offset += limit;
  if (offset >= total) break;
}

Rate limits

The API enforces a limit of 60 requests per minute per tenant, using a sliding window. When you exceed the limit, you receive a 429 Too Many Requests response.

The following headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429)

Error format

All errors return a JSON body:

{
  "error": "Human-readable error message",
  "details": {
    "field": "Additional context about the error"
  }
}

The details object is optional and present only when additional context is available (e.g. validation errors).

Status codes

Code	Meaning
`200`	Request succeeded
`201`	Resource created
`400`	Bad request — invalid input or missing required field
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — valid key but insufficient permissions
`404`	Resource not found
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

SDK

If you’re using TypeScript, the Rivano SDK wraps the REST API with typed methods, automatic pagination helpers, and retry logic.

npm install @rivano/sdk

import Rivano from '@rivano/sdk';

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

Agents API — Agent management endpoints
Policies API — Policy CRUD endpoints
Traces API — Observability data endpoints
SDK Overview — TypeScript SDK with full type coverage

API Reference Overview