API Reference

The Rivano API is a RESTful JSON API for managing agents, querying traces, configuring policies, and proxying AI requests. All endpoints require authentication.

Base URL

https://api.rivano.ai/v1

For self-hosted instances, replace with your deployment’s URL.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer rv_live_abc123...

API keys are scoped to an organization. Generate them from Settings → API Keys in the dashboard.

Common Headers

Header	Required	Description
Authorization	Yes	Bearer <api-key>
Content-Type	Yes (POST/PUT)	application/json
X-Request-Id	No	Client-generated request ID for tracing

Endpoints

List Agents

GET /v1/agents

Returns all agents in your organization.

Query parameters:

Param	Type	Description
status	string	Filter by status: active, paused, archived
limit	integer	Max results (default 50, max 200)
cursor	string	Pagination cursor from previous response

Response:

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "production-assistant",
      "provider": "openai",
      "model": "gpt-4o",
      "status": "active",
      "created_at": "2025-09-15T10:30:00Z",
      "total_requests": 14523,
      "total_cost": 42.87
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_xyz789"
}

Get Agent

GET /v1/agents/{agent_id}

Returns a single agent with detailed configuration and recent metrics.

Response:

{
  "id": "agent_abc123",
  "name": "production-assistant",
  "provider": "openai",
  "model": "gpt-4o",
  "status": "active",
  "config": {
    "rate_limit": 100,
    "budget_limit_daily": 50.00,
    "pii_detection": true,
    "policies": ["policy_def456"]
  },
  "metrics": {
    "requests_24h": 342,
    "avg_latency_ms": 1240,
    "cost_24h": 2.15,
    "error_rate": 0.003
  },
  "created_at": "2025-09-15T10:30:00Z",
  "updated_at": "2025-12-01T08:15:00Z"
}

List Traces

GET /v1/traces

Returns AI request/response traces with filtering and pagination.

Query parameters:

Param	Type	Description
agent_id	string	Filter by agent
since	ISO 8601	Start time (default: 1 hour ago)
until	ISO 8601	End time (default: now)
status	string	success, error, blocked
has_pii	boolean	Filter traces with PII detections
limit	integer	Max results (default 50, max 200)
cursor	string	Pagination cursor

Response:

{
  "data": [
    {
      "id": "trace_uvw456",
      "agent_id": "agent_abc123",
      "model": "gpt-4o",
      "status": "success",
      "input_tokens": 245,
      "output_tokens": 512,
      "cost": 0.0089,
      "latency_ms": 1150,
      "pii_detected": false,
      "policies_evaluated": 3,
      "policies_blocked": 0,
      "timestamp": "2025-12-01T14:22:33Z"
    }
  ],
  "has_more": false
}

Get Trace

GET /v1/traces/{trace_id}

Returns the full trace including request/response bodies, policy evaluations, and PII detections.

Response includes:

• Full prompt and completion text
• Token-level cost breakdown
• Each policy evaluation result (pass/fail/action taken)
• PII detection spans with entity types and positions
• Provider-level timing breakdown

List Policies

GET /v1/policies

Returns all governance policies configured for your organization.

Response:

{
  "data": [
    {
      "id": "policy_def456",
      "name": "block-pii-in-prompts",
      "status": "active",
      "action": "block",
      "priority": 10,
      "conditions": {
        "direction": "inbound",
        "pii_types": ["ssn", "credit_card"]
      },
      "agents": ["agent_abc123"],
      "created_at": "2025-10-01T12:00:00Z"
    }
  ]
}

Proxy Endpoint

POST /v1/proxy/{provider}/chat/completions

The core proxy endpoint. Forwards AI requests to the specified provider while applying policies, logging traces, and tracking costs.

Supported providers: openai, anthropic, google, mistral, cohere

Required headers:

Header	Description
Authorization	Your provider’s API key (e.g., OpenAI key)
X-Rivano-Agent	Your Rivano agent ID
X-Rivano-Key	Your Rivano API key

Request body: Pass the provider’s native request format unchanged. Rivano proxies it transparently.

Response: The provider’s native response format, plus these added headers:

Header	Description
X-Rivano-Trace-Id	Trace ID for this request
X-Rivano-Cost	Estimated cost in USD
X-Rivano-Policies	Number of policies evaluated

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 60 requests/min exceeded. Retry after 12s.",
    "request_id": "req_abc123"
  }
}

Status	Code	Description
400	bad_request	Invalid request body or parameters
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks required permissions
404	not_found	Resource does not exist
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error (include request_id in support tickets)