Getting started

One OpenAI-compatible endpoint for chat, streaming, embeddings, and images — backed by Riven’s own on-prem models plus routed frontier models. This page takes you from zero to a working request.

1. Get an API key#

Every request is authenticated with a Riven API key — a bearer token that starts with rvn_.

Sign in at console.rivenai.io.
Open Keys in the sidebar and click New key.
Copy the key value and store it as an environment variable — treat it like a password.

shell

export RIVEN_API_KEY="rvn_..."

Keys can also be minted, rotated, and revoked programmatically — see Authentication & keys.

2. Make your first request#

The base URL is https://api.rivenai.io. Chat completions are OpenAI-compatible, so existing OpenAI SDKs work by changing the base URL and key.

curl

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

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-core",
    messages=[{"role": "user", "content": "Say hello from Riven."}],
    max_tokens=100,
)
print(resp.choices[0].message.content)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.rivenai.io/v1",
  apiKey: process.env.RIVEN_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "riven-core",
  messages: [{ role: "user", content: "Say hello from Riven." }],
  max_tokens: 100,
});
console.log(resp.choices[0].message.content);

3. Stream the response#

Set "stream": true to receive server-sent events with OpenAI-compatible chat.completion.chunk objects as tokens are generated.

curl

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

4. Pick a model#

riven-core is the balanced flagship tier and a safe default. List everything available to your key with a public, unauthenticated call:

curl

curl https://api.rivenai.io/v1/models

Browse capabilities and plan availability in Models & usage. Some models require a paid plan — requests beyond your plan return a structured rate_limit_exceeded error (see Errors).

5. Check your usage#

curl

curl https://api.rivenai.io/billing/quota \
  -H "Authorization: Bearer $RIVEN_API_KEY"

Returns your plan, usage against the current billing window, and the reset date. Quota state is also attached to every completion response via x-riven-quota-* headers — see API reference → Quota.