Base URL https://api.rivenai.io. All endpoints accept and return JSON. Authenticate with Authorization: Bearer rvn_... (see Authentication & Keys). The chat, embeddings, and models endpoints are OpenAI-compatible: official OpenAI SDKs work by pointing base_url at https://api.rivenai.io/v1.
| Parameter | Type | Notes |
|---|---|---|
model | string | A Riven model ID from the catalog. Defaults to riven-chat-md if omitted. |
messages | array | OpenAI-format message objects (role, content). |
max_tokens | integer | Output token cap. For riven-ultra-pro allow ≥2000 or disable thinking mode (see below). |
stream | boolean | When 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_kwargs | object | Backend template options. {"enable_thinking": false} disables extended thinking on riven-ultra-pro. |
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}'{
"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.
| Header | Meaning |
|---|---|
x-riven-upstream | Identifier of the serving pool that produced the answer. |
x-riven-quota-plan / -used / -limit / -reset | Your plan slug and live usage against the current billing window. |
x-riven-smart-route | Present when a generic alias was upgraded by smart routing (e.g. for time-sensitive queries). Explicit model picks are never rewritten. |
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.
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"rvn-assistant-v2","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"},"finish_reason":null}]}Models: riven-embed, riven-embed-fast. input accepts a single string or an array of strings; vectors are 768-dimensional.
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"]}'{
"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 }
}Model: riven-image. Returns a base64-encoded PNG in data[0].b64_json, with image-token usage accounting.
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"}'{
"created": 1783966736,
"data": [{ "b64_json": "iVBORw0KGgo..." }],
"usage": { "input_tokens": 39, "output_tokens": 1056, "total_tokens": 1095 }
}Public — no authentication required. Returns the live model catalog.
curl https://api.rivenai.io/v1/models
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.
curl https://api.rivenai.io/billing/quota -H "Authorization: Bearer $RIVEN_API_KEY"
{
"object": "quota",
"planSlug": "free",
"used": 12,
"limit": 100,
"remaining": 88,
"resetAt": "2026-08-01T00:00:00.000Z",
"unit": "usd",
"keyPrefix": "rvn_a1b2...",
"source": "control"
}Two independent controls apply to every key:
retry_after_ms. Plan-gated models also surface here as type: "plan_limit".code: "quota_exceeded", the reset date, and a top-up URL.See Errors for the full error index with example payloads.