Riven API

Live

One OpenAI-compatible gateway in front of 75 live models. Point an existing SDK at api.rivenai.io, change the key, and the rest of your code stays put.

Service: api
URL: api.rivenai.io

The Riven API is the single entry point for model access. It speaks the OpenAI wire format, so any client library that accepts a custom base URL works unmodified — the difference is what happens behind the request, where Riven Ultra Router resolves your model name to a healthy pool, on-prem first.

Base URL and authentication#

shell

export RIVEN_BASE_URL="https://api.rivenai.io/v1"
export RIVEN_API_KEY="rvn_..."

Keys are bearer tokens prefixed rvn_. See Authentication & keys for issuing, rotating, and revoking them, and Riven Keymaster for how they are stored.

Core endpoints#

POST/v1/chat/completions

POST/v1/embeddings

GET/v1/models

GET/billing/quota

The full parameter and response reference lives in the API reference; error codes are in Errors.

First request#

curl

curl https://api.rivenai.io/v1/chat/completions \
  -H "Authorization: Bearer $RIVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "riven-best",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.rivenai.io/v1",
    api_key=os.environ["RIVEN_API_KEY"],
)

resp = client.chat.completions.create(
    model="riven-best",
    messages=[{"role": "user", "content": "Hello"}],
)

Response headers#

Header	Meaning
`x-riven-upstream`	Which pool served the request — on-prem node or cloud provider
`x-riven-smart-route`	Present when a routed alias resolved to a concrete tier
`x-riven-quota-remaining`	Tokens left in the current window
`x-riven-quota-reset`	When the window rolls over

Model IDs are stable aliases, not provider model names. riven-best keeps working when the pool behind it changes — see Models & usage for the tier list and token multipliers.

What the gateway does for you#

Routing — alias resolution and failover through Riven Ultra Router.
Metering — token accounting and cost attribution via Riven Pricing Brain.
Observability — per-request traces in Riven Telemetry.
Tools — server-side tool execution through Riven Cortex.
Grounding — optional web-grounded answers via Riven Grounding.

Search docs