Getting Started

The Riven API gives you one OpenAI-compatible endpoint for chat, streaming, embeddings, and image generation — backed by Riven's own hosted 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_.

  1. Sign in at console.rivenai.io.
  2. Open Keys in the sidebar and click New key.
  3. 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 the Model Catalog. 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.

Next steps