RivenGet started

Search docs

Find a page across the Riven documentation

API reference

Base URL https://api.rivenai.io. All endpoints accept and return JSON. Authenticate with Authorization: Bearer rvn_....

The chat, embeddings, and models endpoints are OpenAI-compatible: official OpenAI SDKs work by pointing base_url at https://api.rivenai.io/v1. See Authentication & keys for how to obtain a key.

Chat#

POST/v1/chat/completions
ParameterTypeNotes
modelstringA Riven model ID from the catalog. Defaults to riven-core if omitted.
messagesarrayOpenAI-format message objects (role, content).
max_tokensintegerOutput token cap. For riven-ultra-pro allow ≥2000 or disable thinking mode.
streambooleanWhen true, responds with server-sent events of chat.completion.chunk objects.
temperature, top_p, stop, …—Standard OpenAI sampling parameters are passed through to the serving backend.
chat_template_kwargsobjectBackend template options. {"enable_thinking": false} disables extended thinking on riven-ultra-pro.
toolsarrayTool definitions. Cortex-hosted tools execute server-side — see Riven Cortex.
request
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": "Hello"}], "max_tokens": 100}'
response (abridged)
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "rvn-assistant-v2",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello! ..." }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21 }
}

The response model field reports the backend that actually served the request. Brand IDs stay stable; backends may be upgraded or failed-over without an API change.

Response headers

HeaderMeaning
x-riven-upstreamIdentifier of the serving pool that produced the answer.
x-riven-quota-plan / -used / -limit / -resetYour plan slug and live usage against the current billing window.
x-riven-smart-routePresent when a generic alias was upgraded by smart routing (e.g. for time-sensitive queries). Explicit model picks are never rewritten.

Streaming

With "stream": true the response is text/event-stream; each data: line carries an OpenAI-compatible chunk with a delta. OpenAI SDK streaming helpers work unchanged.

stream chunk
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"rvn-assistant-v2","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"},"finish_reason":null}]}

Embeddings#

POST/v1/embeddings

Models: riven-embed, riven-embed-fast. input accepts a single string or an array of strings; vectors are 768-dimensional.

request
curl https://api.rivenai.io/v1/embeddings \
  -H "Authorization: Bearer $RIVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "riven-embed", "input": ["first text", "second text"]}'
response (abridged)
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [-0.997, 0.234, ...] },
    { "object": "embedding", "index": 1, "embedding": [0.421, -0.138, ...] }
  ],
  "model": "riven-embed",
  "usage": { "prompt_tokens": 4, "total_tokens": 4 }
}

Image generation#

POST/v1/images/generations

Model: riven-image. Returns a base64-encoded PNG in data[0].b64_json, with image-token usage accounting.

request
curl https://api.rivenai.io/v1/images/generations \
  -H "Authorization: Bearer $RIVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "riven-image", "prompt": "a forge hammer resting on an anvil, flat vector style", "size": "1024x1024"}'
response (abridged)
{
  "created": 1783966736,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "usage": { "input_tokens": 39, "output_tokens": 1056, "total_tokens": 1095 }
}

Models#

GET/v1/models

Public — no authentication required. Returns the live model catalog.

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

Quota#

GET/billing/quota

Plan allotment and recorded spend for the calling key in the current billing window, as tracked by the governance layer. Spend aggregation is asynchronous — very recent requests may not be reflected immediately.

request
curl https://api.rivenai.io/billing/quota -H "Authorization: Bearer $RIVEN_API_KEY"
response
{
  "object": "quota",
  "planSlug": "free",
  "used": 12,
  "limit": 100,
  "remaining": 88,
  "resetAt": "2026-08-01T00:00:00.000Z",
  "unit": "usd",
  "keyPrefix": "rvn_a1b2...",
  "source": "control"
}

The "source": "control" field names Riven Control as the governance layer that owns the numbers.

Rate limits & quotas#

Two independent controls apply to every key:

  • Burst rate limits (requests/min and tokens/min, set by your plan) return HTTP 429 with retry_after_ms. Plan-gated models also surface here as type: "plan_limit".
  • Monthly quota (your billing-cycle allowance) returns HTTP 402 with code: "quota_exceeded", the reset date, and a top-up URL.

See Errors for the full error index with example payloads.