How it works Pricing Docs Book a demo Login
Documentation

Rouva Docs

Connect your app to Rouva, then look up what each part does. Each section opens with the essentials; limits and edge cases sit under Details.

Updated on November 9, 2026

On this page
Get started

Quick start

  1. Create an account at app.rouva.io and add one or more AI provider keys on the Providers page.
  2. Generate a gateway key on the Gateway page. It starts with rva_.
  3. Send a request with the SDK, any OpenAI-compatible client, or plain HTTP.

SDK

The Node.js SDK: one client for every connected provider, shaped like the OpenAI SDK.

npm install @rouvanpm/rouva
import { Rouva } from '@rouvanpm/rouva'

const rouva = new Rouva({ apiKey: 'rva_your_key' })

const response = await rouva.chat.completions.create({
  messages: [{ role: 'user', content: 'Your prompt here' }],
})
  • No model: Rouva picks the cheapest capable model for the prompt.
  • A model: used as a cost ceiling. Rouva may pick a cheaper capable model and records the saving against yours.
  • Options: apiKey (required, your rva_ key) and baseURL (optional, another gateway URL).
Switching from the OpenAI or Anthropic SDK

Change the import and the client. The message format is the same, so the rest of your code stays.

// Before (OpenAI)
import OpenAI from 'openai'
const openai = new OpenAI({ apiKey: '...' })
const res = await openai.chat.completions.create({ messages, model: 'gpt-6-sol' })

// Before (Anthropic)
import Anthropic from '@anthropic-ai/sdk'
const anthropic = new Anthropic({ apiKey: '...' })
const res = await anthropic.messages.create({ messages, model: 'claude-sonnet-4-6', max_tokens: 1024 })

// After — one client, any provider, intelligently routed
import { Rouva } from '@rouvanpm/rouva'
const rouva = new Rouva({ apiKey: 'rva_...' })
const res = await rouva.chat.completions.create({ messages, model: 'gpt-6-sol' }) // model optional

Framework quickstarts

  • Any client that speaks OpenAI's Chat Completions works: set its base URL to https://app.rouva.io/v1 and its API key to your rva_ key.
  • On /v1 the model you name is used exactly for non-tools requests (routing overrides still apply). The response headers say what ran.
  • Each example was tested with the framework release current in October 2026.

Vercel AI SDK

Use the OpenAI-compatible provider: it calls Chat Completions, which is what Rouva serves.

npm install ai @ai-sdk/openai-compatible
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText, streamText } from "ai";

const rouva = createOpenAICompatible({
  name: "rouva",
  baseURL: "https://app.rouva.io/v1",
  apiKey: process.env.ROUVA_API_KEY,
});

const { text } = await generateText({
  model: rouva("gpt-6-luna"),
  prompt: "Where is the Eiffel Tower?",
});

const result = streamText({
  model: rouva("gpt-6-luna"),
  prompt: "Where is the Eiffel Tower?",
});
for await (const chunk of result.textStream) process.stdout.write(chunk);

OpenAI SDK (Node)

withResponse() gives you the routing headers alongside the parsed completion.

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.rouva.io/v1",
  apiKey: process.env.ROUVA_API_KEY,
});

const { data: completion, response } = await client.chat.completions
  .create({
    model: "gpt-6-luna",
    messages: [{ role: "user", content: "Where is the Eiffel Tower?" }],
  })
  .withResponse();

console.log(completion.choices[0].message.content);
console.log(response.headers.get("x-rouva-model"), response.headers.get("x-rouva-request-id"));

OpenAI SDK (Python)

with_raw_response gives you the routing headers alongside the parsed completion.

pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://app.rouva.io/v1",
    api_key=os.environ["ROUVA_API_KEY"],
)

raw = client.chat.completions.with_raw_response.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Where is the Eiffel Tower?"}],
)
completion = raw.parse()
print(completion.choices[0].message.content)
print(raw.headers.get("x-rouva-model"), raw.headers.get("x-rouva-request-id"))

LangChain (JS)

npm install @langchain/openai
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-6-luna",
  apiKey: process.env.ROUVA_API_KEY,
  configuration: { baseURL: "https://app.rouva.io/v1" },
});

const reply = await llm.invoke("Where is the Eiffel Tower?");
console.log(reply.content);

for await (const chunk of await llm.stream("Where is the Eiffel Tower?")) process.stdout.write(String(chunk.content));

LangChain (Python)

pip install langchain-openai
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-6-luna",
    base_url="https://app.rouva.io/v1",
    api_key=os.environ["ROUVA_API_KEY"],
)

print(llm.invoke("Where is the Eiffel Tower?").content)

for chunk in llm.stream("Where is the Eiffel Tower?"):
    print(chunk.content, end="")

LlamaIndex

is_chat_model=True sends Chat Completions requests.

pip install llama-index-llms-openai-like
import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="gpt-6-luna",
    api_base="https://app.rouva.io/v1",
    api_key=os.environ["ROUVA_API_KEY"],
    is_chat_model=True,
)

print(llm.complete("Where is the Eiffel Tower?"))

LiteLLM

The openai/ prefix tells LiteLLM to speak the OpenAI format to Rouva's base URL.

pip install litellm
import os
import litellm

response = litellm.completion(
    model="openai/gpt-6-luna",
    api_base="https://app.rouva.io/v1",
    api_key=os.environ["ROUVA_API_KEY"],
    messages=[{"role": "user", "content": "Where is the Eiffel Tower?"}],
)
print(response.choices[0].message.content)
Sending requests

Endpoints

Three endpoints, all on https://app.rouva.io. Every call needs Authorization: Bearer rva_your_key; POSTs also take Content-Type: application/json.

POST/api/gateway/messagesNative gateway, routed
  • Routes each prompt to the cheapest capable model on your connected providers (see How routing works).
  • Streams by default (SSE). stream: false returns JSON.
  • Answers come in the wire format of the provider that served them (OpenAI or Anthropic); the SDK normalises both.
Request parameters
FieldTypeDescription
messages Requiredarray{ role, content } objects. Roles: system, user, assistant, tool. Content must be a string except on tools requests.
modelstringOmit to auto-route. Otherwise a cost ceiling: Rouva may route cheaper and tracks savings against it. Used exactly when Intelligent Routing is off, and on tools requests (unless a same-provider routing override applies). A workspace member's model allowlist can substitute the cheapest permitted model.
providerstringanthropic, openai, gemini, mistral, deepseek, xai, zai, alibaba, moonshot, minimax. Without model: route within this provider (an account routing override still applies; with routing off, its default model). 402 if its key isn't connected; with routing on, 400 if none of the models Rouva routes to on it fits the request. With model: the model must belong to it (400 otherwise).
systemstring | arraySystem prompt: a string or Anthropic-style text blocks.
max_tokensnumberDefault 4096. max_completion_tokens is accepted as an alias.
temperaturenumber0–1. Left out for reasoning models and for Claude models that reject it (Opus 4.7 and newer, Sonnet 5 and newer, Fable).
streambooleanDefault true.
tools, tool_choicearray, string | objectForwarded verbatim; tools needs a model. See Tools and agents.
parallel_tool_callsbooleanWith tools only. false = at most one tool call per turn (for Claude, Rouva sets disable_parallel_tool_use).
top_pnumberNucleus sampling; 1 counts as omitted. Not supported on OpenAI reasoning models; left out for the same Claude models as temperature.
stopstring | string[]Up to 4 stop sequences. Not supported on OpenAI or xAI reasoning models (e.g. grok-4.7): a request pinned to one gets a 400, and Intelligent Routing skips them when stop is set.
seedintegerOpenAI models only; pins routing to OpenAI.
response_formatobjectJSON mode or a JSON schema. See Structured output.
reasoning_effortstringnone to max. See Reasoning effort.
service_tierstringdefault (or standard_only) asks OpenAI and Anthropic for their standard tier, wherever the request is routed. auto or leaving it out uses your provider account's own setting. flex, priority and scale are refused: Rouva bills standard prices.
metadataobjectFlat string map stored with the request, up to 10 keys. customer_id powers Cost per customer.
Unsupported options are rejected with an explicit 400, never silently ignored: logit_bias, logprobs / top_logprobs, n ≠ 1, non-zero penalties, service_tier flex / priority / scale, and the legacy functions/function_call fields. Token ids in logit_bias belong to one model's tokenizer, and of the models Rouva routes to only OpenAI's retiring GPT-4 models accept it. Few return logprobs (most OpenAI reasoning models refuse it), so a routed request couldn't count on it. Flex, priority and scale tiers cost differently from the standard prices Rouva bills.
Response formats

OpenAI-format stream (SSE)

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"Hello"},"index":0}]}
data: {"id":"chatcmpl-...","choices":[{"delta":{},"finish_reason":"stop","index":0}]}
data: [DONE]

Anthropic-format stream (SSE)

data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"}}
data: {"type":"message_stop"}

Buffered JSON (stream: false), OpenAI format

{"id":"chatcmpl-...","choices":[{"message":{"role":"assistant","content":"Hello"},"finish_reason":"stop","index":0}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}
POST/v1/chat/completionsOpenAI-compatible

A drop-in for the OpenAI API: point any OpenAI SDK or compatible client at https://app.rouva.io/v1 with your rva_ key.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.rouva.io/v1",
  apiKey: process.env.ROUVA_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [{ role: "user", content: "Hello" }],
});
  • model is required and used exactly. A routing override for the task type still applies.
  • Tools requests with Intelligent Routing on: the named model is a ceiling, and Rouva may use a cheaper model on the same provider.
  • stream defaults to false, as in OpenAI's API.
  • No provider field: it's inferred from the model.
Details
  • Serves OpenAI-format providers (OpenAI, Gemini, DeepSeek, Mistral, Moonshot, xAI, Z.ai, Alibaba Qwen, MiniMax). A non-tools request that a routing override sends to Claude comes back translated to OpenAI's format, streaming or not.
  • Tools requests stay on the named model's provider; an override applies only when it targets that provider.
  • Anthropic-format tool definitions (input_schema) are rejected; use OpenAI's format.
  • stream_options accepts only omitted, {} or { include_usage: true }; anything else is a 400.
  • No fallback to another model on a provider error.
POST/api/gateway/runAgent loop, run by Rouva

Hand the whole agent loop to Rouva: it calls the model, sends each tool call to your handler URL (in parallel), adds the results, and repeats until the model stops or a limit is hit.

const result = await rouva.run({
  model: 'claude-haiku-4-5-20251001',
  messages: [{ role: 'user', content: 'Weather in Paris and London?' }],
  tools: [{ name: 'get_weather', description: 'Get weather for a city',
    input_schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } }],
  tool_handlers: { get_weather: 'https://api.example.com/weather' },
  max_turns: 5,
  session_budget_usd: 0.10,
})
  • Tools in OpenAI or Anthropic format; Rouva translates between them (see Tools across providers).
  • Handlers receive POST { name, arguments } and must be public HTTPS URLs.
  • Every turn is one row in your request log, grouped by session.
Request parameters
ParameterTypeDescription
messages RequiredarrayThe conversation so far, usually one user message.
tools RequiredarrayTool definitions, OpenAI or Anthropic format.
tool_handlers RequiredobjectTool name → public HTTPS handler URL.
model RequiredstringThe model to use.
providerstringNeeded only when the model ID isn't listed and has no known provider prefix.
max_turnsnumberMost loop iterations (default 10).
max_tokensnumberMost tokens per turn (default 4096).
temperaturenumber0–1.
session_budget_usdnumberThe loop stops after the turn that takes the run's spend to this value. That turn is billed in full, so spend can pass the limit by one turn.

response_format, reasoning_effort and parallel_tool_calls aren't accepted on /run.

Response
{
  "content": "The weather in Paris is 18°C and partly cloudy.",
  "turns": 2,
  "tool_calls_made": 1,
  "session_id": "rva-sess-abc123xyz",
  "finish_reason": "stop",
  "session_cost_usd": 0.000041
}

Tools and agents

Tool calls pass through in the format you send. Write tools in the schema of the provider that owns your model.

  • Pin a model. Tools requests need a model; Rouva doesn't swap it for another provider's (tool schemas are provider-specific).
  • Both styles work: OpenAI tool_calls and role: "tool" messages, or Anthropic tool_use / tool_result blocks.
  • Not scored, not trimmed. Tools requests skip the quality judge and whitespace trimming.
  • Detect tool calls from the content, not the stop reason. A forced tool_choice on an OpenAI-format provider can return finish_reason: "stop" with tool_calls present.
Details

tools, tool_choice, tool calls and tool results are forwarded to the chosen model with their content and whitespace unchanged. For Claude, each message is rebuilt from the fields Anthropic accepts (unrecognized message fields are dropped); for OpenAI-format providers, messages are passed through as sent, so an unrecognized field reaches the provider and may be rejected there. System messages move to Anthropic's top-level system parameter when routing to Claude, and requests to listed Claude models may get prompt-caching markers (see Request handling).

GPT-5.6, GPT-6.2 Sol and Astra, GPT-6.1 Sol and GPT-6 Astra serve tool calling only through OpenAI's Responses API, and so do GPT-6 Luna / Sol and GPT-6.1 Terra with a reasoning_effort other than none. Rouva calls the Responses API for you (with store: false, so OpenAI keeps no conversation state) and converts both ways: you send and receive Chat Completions as with any OpenAI model. It has no seed or stop and needs max_tokens of at least 16, so those requests get a 400. /api/gateway/run still refuses these models.

Where to look for tool calls: tool_calls in the deltas (or on message with stream: false) for OpenAI-format providers; tool_use content blocks for Anthropic.

Tools across providers (/run)

  • On /api/gateway/run, write tools in OpenAI or Anthropic format: Rouva detects each one's format by its shape and converts the whole conversation for the model it picked.
  • With Intelligent Routing on, Rouva picks the model once, before the loop, across your Anthropic and OpenAI-compatible providers, then uses it for every turn. Automatic routing never picks one pricier than your pinned model. Routing overrides apply as policy and aren't price-constrained: an override can choose a pricier model.
  • Tools already in the target provider's format are sent as written, extensions like strict or cache_control included. Tool-call IDs, arguments, names and results are kept as sent.
  • System messages go to Anthropic's top-level system for Claude, and stay role: "system" for OpenAI-compatible providers.
  • Content that can't be translated keeps the run off the other format's providers.
What keeps a run on one side
  • Blocks OpenAI-compatible providers (Anthropic stays eligible): Anthropic images, document or thinking blocks; cache_control on messages, text blocks, tool schemas or tool results; is_error on tool results; documents or images inside tool results; thought_signature or other Anthropic-only fields on tool calls.
  • Blocks Anthropic (OpenAI-compatible providers stay eligible): developer messages; file or audio parts (image_url is translated only inside tool results); reasoning_content, audio or refusal fields; a participant name; strict or other OpenAI-only tool-schema fields; malformed tool-call arguments; tool-result parts or metadata it can't translate.
  • Never between two OpenAI-compatible providers (e.g. OpenAI → DeepSeek): their extensions don't carry over safely.
  • The within-provider fallback is unaffected. A same-provider routing override whose model uses the other format may be skipped when the run holds content that format can't take.
The same tool in both formats
// OpenAI format
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get weather for a city",
    "parameters": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  }
}

// Anthropic format
{
  "name": "get_weather",
  "description": "Get weather for a city",
  "input_schema": {
    "type": "object",
    "properties": { "city": { "type": "string" } },
    "required": ["city"]
  }
}

Structured output

Send response_format in OpenAI's format on /api/gateway/messages or /v1/chat/completions.

  • { type: "json_object" }: any valid JSON. Needs the word "json" somewhere in your messages or system prompt (400 otherwise; several providers require it).
  • { type: "json_schema", json_schema: { name, schema, strict: true } }: JSON that matches your schema. For Claude it's sent as output_config.format, and the JSON arrives as the answer text.
  • Routing, overrides, fallbacks and member allowlists only pick models that support your format. If none of your connected models does, you get a 400, unless you named a model, which is then used as named.
{
  "messages": [{ "role": "user", "content": "Where is the Eiffel Tower?" }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "place",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": { "city": { "type": "string" }, "country": { "type": "string" } },
        "required": ["city", "country"],
        "additionalProperties": false
      }
    }
  }
}
Providerjson_objectjson_schema
OpenAIYesYes
AnthropicNo (400)Yes, within Anthropic's schema rules
Google Gemini—Yes
DeepSeekYes—
Mistral, Moonshot, xAIYesYes
Z.aiYes (not GLM-4.7-Flash)—
AlibabaYesQwen3.7 / Qwen3.8 models (not Omni)
MiniMax——
Claude's schema rules
  • Routing picks Claude for a schema only when every object sets additionalProperties: false and the schema avoids keywords Anthropic rejects (such as minimum, maxLength and maxItems).
  • Claude isn't picked when the conversation ends with an assistant message (a prefill), which Anthropic doesn't allow with a schema.
  • A model you name is sent the request as written and its provider reports what it doesn't support, except json_object or a prefill on Claude, which get Rouva's 400.

Reasoning effort

Send reasoning_effort in OpenAI's format on /api/gateway/messages or /v1/chat/completions.

  • OpenAI and DeepSeek models get it as is; Claude gets it as output_config.effort.
  • Routing only picks a model from the table below that takes your value. If none of your connected models does, you get a 400, unless you named a model, which is then used as named.
  • A model in the table that doesn't take the value gets Rouva's 400 listing the values it does take. Other providers' models are sent the value as written.
ModelsValues
GPT-5, GPT-5 Mini, GPT-5 Nano (retiring 2026-12-11: used only when named)minimal, low, medium, high
GPT-5.4 Mini, GPT-5.6 Luna / Terra / Sol, GPT-6 Luna / Sol, GPT-6.1 Terranone, low, medium, high, xhigh
GPT-6.2 Sol / Astra, GPT-6.1 Sol, GPT-6 Astralow, medium, high, xhigh
Claude Sonnet 4.6, Opus 4.6low, medium, high, max
Claude Sonnet 5 and newer, Opus 4.7 and newer, Haiku 5.5, Fablelow, medium, high, xhigh, max
DeepSeek V4 Pronone, minimal, low, medium, high, xhigh, max
DeepSeek Flash Thinkingminimal, low, medium, high, xhigh, max
DeepSeek Flash (thinking off)none
GPT-4o, GPT-4.1 families, Claude Haiku 4.5None
GPT-6 reasoning on and off
  • On GPT-6 Luna and Sol and GPT-6.1 Terra, none turns reasoning off: temperature, top_p and function tools then work.
  • Any other value turns it on: top_p then gets a 400, and function tools go through OpenAI's Responses API (see Tools and agents).
  • Without reasoning_effort, Rouva turns reasoning off for you when a request needs it (tools, top_p, or a small max_tokens).
  • Values were checked against each provider on October 21–22, 2026 (GPT-6.1 Terra, GPT-6 Astra and Claude Haiku 5.5 on October 27, Claude Fable 5.2 on November 11, GPT-6.2 Sol and Astra on November 18).

Sessions

Group the turns of an agent run under one session ID in your request log.

  • Send an x-rouva-session-id header, or call rouva.startSession() in the SDK.
  • Call rouva.endSession() when the run is done, so later requests aren't grouped with it.
  • /api/gateway/run creates a session for you.
POST /api/gateway/messages
Authorization: Bearer rva_your_key
x-rouva-session-id: my-agent-run-001
Content-Type: application/json
Understanding responses

Response headers

Responses from /api/gateway/messages and /v1/chat/completions say what Rouva decided, so you can log it without opening the dashboard.

HeaderWhenValue
X-Rouva-Request-IdOnce the request is recordedIts id in your request log. Look it up with Cost lookup.
X-Rouva-ModelOnce a model is chosenThe model that served it (after a fallback, the fallback model).
X-Rouva-ProviderOnce a model is chosenIts provider, e.g. openai, anthropic.
X-Rouva-Requested-ModelWhen it differsThe model you named, when another one served.
X-Rouva-Task-TypeOnce a model is chosen (empty on replays)The task type, e.g. code. May be empty when the task type couldn't change the model (see Details).
X-Rouva-Route-ReasonOnce a model is chosenintelligent, override, allowlist, fallback, no_key_fallback, direct, escalation, or dedup on a replay.
X-Rouva-Cost-UsdNon-streamingCost in USD, six decimals. Left out when the provider reported no usage or the model has no price.
X-Rouva-Saved-UsdNon-streamingSaved against the model you named, or the priciest connected model for the task. Negative when the route cost more.
X-Rouva-RefusalRouva refused the requestWhy. See Errors and refusals.
X-Rouva-DedupA replay1 when an identical request was answered from the 60-second cache (see Request handling).
Server-TimingEvery response (also /run)Milliseconds per step, e.g. auth, classify, upstream (the provider), rouva (Rouva's own time), total.
  • A stream's cost is known only after its last chunk, after the headers are sent: read it back with the request id.
  • A replay costs nothing: X-Rouva-Cost-Usd: 0.000000, X-Rouva-Model and X-Rouva-Provider of the original, and no request id or requested model.
Details
  • Headers are on successful responses, provider errors, and Rouva's own refusals once a model is chosen (a spend cap, a deadline, or a model that can't take the request, such as a response_format it doesn't serve). On such a refusal, X-Rouva-Model is the model Rouva refused to send to.
  • Errors returned before a model is chosen carry none of them: a malformed body, a missing provider key, and every refusal from a workspace member's model allowlist.
  • X-Rouva-Task-Type: when the task type can't change the model (routing off, or a pinned model with no routing override), Rouva classifies while the provider answers, so the header may be empty, usually on streams. The lookup returns it once recorded.
  • Server-Timing also has rate and settle (recording the cost, before a non-streaming answer returns). For a stream, it covers the time until the stream starts. Browser developer tools and curl -v show it.

Cost lookup

GET /api/gateway/requests/{id} returns a request's model, tokens, cost, savings and quality score.

GET /api/gateway/requests/8f3c2a1e-4b5d-4c6e-9f70-1a2b3c4d5e6f
Authorization: Bearer rva_your_key

{
  "id": "8f3c2a1e-4b5d-4c6e-9f70-1a2b3c4d5e6f",
  "status": "scored",
  "provider": "openai",
  "model": "gpt-6-luna",
  "requested_model": null,
  "task_type": "simple_qa",
  "route_reason": "intelligent",
  "input_tokens": 12,
  "output_tokens": 48,
  "cost_usd": 0.000025,
  "saved_usd": 0.000310,
  "quality_score": 0.92,
  "judge_status": "scored",
  "finish_reason": "stop",
  "session_id": null,
  "created_at": "2026-10-21T10:00:00Z",
  "dashboard_url": "https://app.rouva.io/dashboard?request=8f3c2a1e-…#request-log"
}
statusMeaning
pendingStill running.
settledTokens and cost are final.
scoredA quality score is recorded (quality_score, 0–1).
incompleteThe full charge isn't known; the provider may have billed more than the recorded cost.
  • A key reads only its own requests; another account's id is a 404.
  • A request older than your plan's history (7 days on Free, 30 on Starter, 90 on Team) is a 404 with "code": "outside_history" and history_days. It isn't deleted: a plan with a longer history shows it again.
  • dashboard_url opens the request in your request log.
Details
  • The score is usually Rouva's judge. When the judge didn't run, Rouva's own checks can still score an answer they flag (a refusal or a repetition loop); judge_status says which. Tools requests aren't scored, so their quality_score stays null. Scoring depends on the plan: none on Free (judge_status skipped_plan, not even the built-in checks' score), half of the requests on Starter (sampled_out_plan for the others), every request on Team, and none past a paid plan's included requests (skipped_overage). An unscored request ends as settled, never scored.
  • A request is incomplete when a stream was cut short (it records what the provider reported before stopping), when a long conversation Rouva summarized may include a summary call whose usage wasn't reported, or when the model has no price (a fine-tune, a new snapshot: recorded at $0). Non-streaming responses leave out the cost headers in the same cases.
  • Copy as curl on an expanded request-log row copies the request for POST /api/gateway/messages with the model you named, its session header and $ROUVA_API_KEY. Rouva doesn't store prompts, so the messages are a placeholder; a comment shows how to pin the model that served it.

Errors and refusals

When Rouva refuses a request itself for a spend cap, the rate limit, the plan's monthly requests, pricing or time, before anything is sent to the provider, the response carries an X-Rouva-Refusal header naming why.

X-Rouva-RefusalStatusMeaning
key_cap429The key's monthly spend cap is reached, or this request's worst case doesn't fit in what's left (see Spend caps).
member_cap429The same for a workspace member's cap.
customer_cap429The request's customer_id reached its monthly cap (see Customer caps).
rate429Too many requests this minute.
plan_limit429The account used its plan's requests for the month (Free: 10,000). Requests resume on the 1st (UTC), or upgrade on the Billing page. Paid plans aren't refused.
unpriced400The model has no usable price where one is required: a spend-capped key, or a /run with session_budget_usd.
unbounded400A capped key sent input, or chose a model, whose cost can't be bounded.
deadline504A single request ran out of its time budget before the provider was called. Nothing was sent: retry it as a new request.
  • 429 and 504 refusals carry Retry-After. For a reached cap or plan limit, that's the seconds until the 1st of next month (UTC).
  • The Node SDK exposes the header as RouvaError.refusal.
  • Errors returned by the provider never carry it. Other Rouva errors — such as a temporary 503 when spend can't be verified — don't carry it either; read the error message.
Details
  • Deadline: a request's time budget is about 285 seconds, or about 260 for a streamed one, which needs 30 seconds left to start. A /run that runs out of time returns a plain 504 "Run deadline exceeded" instead: earlier turns and their tool calls already ran.
  • Worst case doesn't fit: 429 with Retry-After: 10. Lower max_tokens, shorten the prompt, or wait for requests in flight to settle.
  • Other common errors: 400 for a request Rouva can't serve as written (the message says why), 402 when the model's provider key isn't connected, 403 when a member's model allowlist leaves no model, 503 when a cap or a member's model allowlist can't be checked (never sent unchecked).

Explain a routing decision

POST /api/gateway/explain is a dry run: same body and key as /api/gateway/messages. Nothing is sent to a provider, recorded or charged, and no spend is reserved.

  • Returns the model and provider Rouva would pick, route_reason, the classification, and max_cost_usd (the input as sent plus max_tokens of output: the worst case a spend-capped key reserves).
  • ?endpoint=v1 explains the same body sent to /v1/chat/completions.
  • A request that would be refused returns "would_send": false with the status and error it would get, and the model it would have gone to when one had been chosen.
POST /api/gateway/explain
Authorization: Bearer rva_your_key

{ "model": "gpt-6-sol", "messages": [{ "role": "user", "content": "Summarize this contract…" }] }

{
  "dry_run": true,
  "would_send": true,
  "endpoint": "/api/gateway/messages",
  "provider": "openai",
  "model": "gpt-6-luna",
  "requested_model": "gpt-6-sol",
  "task_type": "summarize",
  "route_reason": "intelligent",
  "classified_by": "jev",
  "classifier_confidence": 0.94,
  "max_tokens": 4096,
  "price_per_1m": { "input": 0.1, "output": 0.5 },
  "max_cost_usd": 0.002061,
  "summarize_history": false,
  "spend_capped": false
}
Limits
  • The prompt is classified exactly as for a real request (cached for 24 hours).
  • Its own rate limit, the same per minute as the gateway's (429 with X-Rouva-Refusal: rate).
  • Not covered: the duplicate-request cache, a spend cap's remaining budget, and what the provider answers (errors and the fallback chain).
Routing

How routing works

With Intelligent Routing on (Settings), Rouva classifies each prompt and sends it to the cheapest model on your connected providers that can handle it.

You sendRouva uses
No modelThe cheapest capable model for the task type.
A model (on /api/gateway/messages)That model or a cheaper capable one. Savings are recorded against it.
A provider, no modelThe cheapest capable model on that provider.
A provider and a modelExactly that model.
A model on /v1, on a tools request to /api/gateway/messages, or with seedExactly that model.
A model with tools on /v1That model or a cheaper one on the same provider.
  • Cheaper means at every prompt length. Wherever Rouva may pick a model other than the one you named, that model's input and output prices must be no higher than the named model's at every prompt size, including any long-prompt rates. For example, Qwen3.7 Flash ($0.03 / $0.13 per 1M tokens up to 32K) never stands in for Qwen Flash ($0.05 / $0.40), because from 32K tokens it costs $0.10 per 1M input.
  • Policy first. A routing override for the task type replaces any of these choices, even with a pricier model: a named model is a ceiling for automatic routing, not for your overrides.
  • Request needs count. Routing only picks models that serve what the request asks for: tools, structured output, reasoning effort, stop, a large max_tokens.
  • Provider errors. On a 429 or 5xx from the provider, /api/gateway/messages retries on another capable model, never one pricier than the model you named (when a routing override chose the model, never pricier than the override's model). Not on /v1, tools requests, seed requests, requests naming both provider and model, or with routing off.
  • Routing off. The model you name is used as named; without one, a default model on a connected provider.
  • Per request. Send X-Rouva-Routing: on or off to turn routing on or off for one request on /api/gateway/messages or /v1, whatever Settings says. Send it to /api/gateway/explain too, so the dry run matches. /run doesn't take it (400). Overrides follow it: with off, they aren't applied. Only the workspace owner's keys may send it; a member's key gets a 400, as does any other value.

Task classification

Before routing, Rouva classifies requests into one of six task types: Summarize, Q&A, Code, Research, Creative and Complex.

  • The task type decides which routing override applies and, for most requests, which models routing chooses from.
  • Requests are classified by Jev, a classification model from TypeSafe. When Jev is unavailable or less than 60% certain, Rouva compares the prompt with examples of each task type (using OpenAI embeddings) instead. If that is inconclusive too, Rouva uses Jev's less certain answer, and a keyword rule only when neither is available.
  • The request log shows each request's task type and what classified it; Jev's show its certainty, e.g. 93% certain.
Caching and data
  • A request with no earlier assistant turns reuses the result for the same prompt from the last 24 hours (10 minutes when a classifier was unavailable and a fallback answered). Conversations with earlier turns are classified fresh each time.
  • A request whose latest message is blank and that has no system or developer prompt is never sent for classification. With either, that prompt is classified.
  • Jev receives the system prompt and the latest message (up to 32,000 characters) and returns only a task type and a confidence score. TypeSafe doesn't use this data to train models and has zero data retention for Rouva's account. See the Privacy Policy.
  • Tools requests on /v1 are routed within the pinned model's provider instead, and a duplicate request answered from the cache isn't classified.

Routing overrides

Pin a model to a task type for your whole account. It's enforced policy: the override beats the model the caller asked for, on every endpoint and SDK, even when it costs more.

  • Set up: Settings → Model overrides. For each task type (Summarize, Q&A, Code, Research, Creative and Complex) pick any model from your connected providers. It applies to the next request.
  • Example: your app asks for gpt-6-sol and your Creative override is claude-sonnet-5: creative prompts go to Claude Sonnet 5.
  • Visible: the request log marks these rows ⊕ override, and X-Rouva-Route-Reason is override.
  • Needs Intelligent Routing on. With it off (in Settings, or with X-Rouva-Routing: off on a request), the caller's model is used as is.
When an override is skipped
  • Incompatible parameters: a seed with a non-OpenAI override, or top_p / stop with an OpenAI reasoning model. A temperature on a reasoning-model override is left out instead.
  • Tools requests stay on their provider: a gpt-6-sol tools request can be overridden to gpt-6-luna, not to claude-sonnet-5. Cross-provider overrides are skipped and the pinned model is used.
  • On /v1, an override to Claude is translated back to OpenAI's format, streaming or not (text only; tools requests never cross providers).

Request handling

Besides routing, the gateway does four things that can change a response or the calls made with your keys.

WhatIn short
Duplicate requestsAn identical request within 60 seconds of a completed one gets the earlier answer, free (X-Rouva-Dedup: 1).
Long-conversation summarizationOlder turns of long conversations routed to Claude are condensed into a summary.
Anthropic prompt cachingRouva adds cache markers on Claude requests, so repeated prompts cost less.
Whitespace trimmingExtra whitespace and blank lines are removed before sending.

How request data is stored and shared is in the Privacy Policy; who pays for what is in the Terms of Service.

Duplicate requests

On /api/gateway/messages and /v1/chat/completions, if an identical request from the same account (same messages, parameters, routing settings and x-rouva-session-id) arrives within 60 seconds after a previous one has completed — typically a client retry — Rouva returns the earlier response instead of calling the provider again, so that retry isn't charged.

  • Retries sent while the original request is still in progress, or in the moment before its response is cached, are not deduplicated: they reach the provider and are charged normally.
  • Streaming tools requests and /api/gateway/run are never deduplicated.
  • To force a fresh answer, change the message content (for non-tools requests, whitespace-only changes don't count because whitespace is normalized first; for tools requests they do), the model, or a generation parameter such as temperature, max_tokens, top_p, stop or seed. Changing metadata doesn't.
  • Retrying a non-streaming request with stream: true can still be served from the cache, but retrying a streamed request with stream: false always reaches the provider (and is charged), because a streamed response can't be returned as JSON.
Long-conversation summarization
  • On /api/gateway/messages and /v1/chat/completions, when a non-tools request is routed to a Claude model other than Claude Haiku and its older turns are long, Rouva condenses those older turns into a short summary before forwarding.
  • The most recent turns are never summarized (they still get whitespace trimming and prompt-caching markers).
  • The summary is an extra request to Claude Haiku using your Anthropic API key (for workspace members, the owner's key), charged to that Anthropic account and reused for 24 hours for the same conversation prefix. It usually lowers the total cost of long conversations.
  • Tools requests and /api/gateway/run are never summarized.
Anthropic prompt caching

When a request is routed to one of the Claude models listed under Supported models, Rouva adds Anthropic prompt-caching markers (cache_control, 5-minute TTL):

  • The system prompt and the last tool definition are marked whenever they are present, whatever the request's length, as long as the request has room left in Anthropic's limit of 4 cache markers per request (markers you set count toward it).
  • The conversation prefix is marked only in multi-turn conversations long enough to benefit (the threshold depends on the model).
  • No markers are added when your system prompt or message content already carries longer-lived markers, and a system block or tool you have already marked is left as is.
  • To set your own markers on a request without tools, send the system prompt as a top-level system array of text blocks with cache_control (message content must be plain strings unless the request includes tools). If the request is routed to a provider other than Anthropic, the blocks are joined into plain text and the markers are dropped.
  • Anthropic bills cache writes above normal input and cache reads far below it, so repeated prompts usually cost less, but a long prompt sent only once can cost slightly more. Short prompts below Anthropic's minimum aren't cached. This applies to tools requests too, on the Anthropic account whose key is used.
  • Rouva also marks claude-sonnet-4-5-20250929, which isn't listed. What counts is the model the request is finally routed to (after any routing override), not the one you named: if that model is any other Claude model ID (for example a new release not yet listed), the request is sent without any markers Rouva adds.
Whitespace trimming

For non-tools requests, leading and trailing whitespace is trimmed and runs of blank lines are collapsed before forwarding. Tools requests are not trimmed.

Supported models

Pass any of these IDs as model. The provider's key must be connected on the Providers page.

  • Unlisted IDs still work when pinned: new releases, dated snapshots like gpt-6-luna-YYYY-MM-DD and fine-tunes like ft:gpt-6-luna:… are matched to their provider by name and forwarded as is.
  • Until Rouva knows an unlisted model's price, its requests are recorded with their tokens at zero cost.

Anthropic

Complex reasoning, coding, and long-context work.

claude-fable-5-2 claude-fable-5-1 claude-fable-5 claude-opus-5-5 claude-opus-5 claude-opus-4-8 claude-opus-4-7 claude-opus-4-6 claude-sonnet-5-5 claude-sonnet-5 claude-sonnet-4-6 claude-haiku-5-5 claude-haiku-4-5-20251001

OpenAI

General-purpose, coding, and vision-heavy tasks.

gpt-6.2-astra gpt-6.2-sol gpt-6-astra gpt-6.1-sol gpt-6.1-terra gpt-6-sol gpt-6-luna gpt-5.4-mini gpt-5.6-luna gpt-5.6-terra gpt-5.6-sol

Google Gemini

Fast multimodal and long-context reasoning.

gemini-4-carbon gemini-4-argon gemini-3.8-flash gemini-3.7-flash gemini-3.6-flash gemini-3.5-flash-lite gemini-2.5-flash gemini-2.5-pro

xAI Grok

Chat, coding, and knowledge work.

grok-4.7 grok-4.6 grok-4.5 grok-4.3 grok-4.20-0309-reasoning

DeepSeek

Strong coding and reasoning with efficient pricing.

deepseek-flash deepseek-flash-think deepseek-v4-pro

Mistral

Lightweight European models for deterministic workloads.

mistral-small-latest mistral-large-4

Moonshot Kimi

Coding, research, and agent workflows.

kimi-k3.1-pro kimi-k3

Z.ai

Long-horizon agent workflows and lightweight tasks.

glm-5.3 glm-5.2 glm-4.7-flash

Alibaba Qwen

High-throughput Chinese frontier models at competitive pricing.

qwen3.8-omni-flash qwen3.8-flash qwen3.7-flash qwen3.7-plus qwen-plus qwen-flash qwen-max

MiniMax

Agentic coding and tool use with 1M-token context.

MiniMax-M3.1-Flash MiniMax-M3
Teams and customers

Team members

Invite teammates to use your provider keys, with a spend cap and a model list for each.

  • Invite: enter an email on the Team page. The link expires after 7 days. After accepting, a member uses their own rva_ key (generated on the Gateway page, or the one they had), which now runs on your provider keys.
  • Spend cap: Edit a member, enter a monthly USD cap, Save cap. See Spend caps.
  • Alerts: when a member's month-to-date spend crosses 80% or 100% of their cap, Rouva emails the member and you (and posts to your Slack, if connected).
  • Model restrictions: in the same panel, tick the models a member may use. None ticked = all models.
  • Remove: Remove on a member's row ends their access; their key no longer authenticates as a member. Cancel pending invites from the Pending invites list.
How model restrictions reroute
  • Restrictions apply after routing and overrides. If the chosen model is allowed, it's used. If not, the gateway transparently reroutes to the permitted model with the lowest combined input and output price (per million tokens) within an eligible set, and returns 403 only if none exists.
  • On /api/gateway/messages, tools requests fall back only to models on the same provider; other requests can cross providers.
  • On /api/gateway/run, a fallback can cross between the Anthropic and OpenAI-compatible formats but not between two OpenAI-compatible providers (e.g. OpenAI → DeepSeek). Anthropic is ruled out when the request has a developer message, OpenAI-only tool-schema fields (e.g. strict) or other OpenAI-only content; other providers are ruled out when it has Anthropic-only content such as cache_control, thinking blocks or is_error on a tool result. If the only permitted model is ruled out, the request returns 403.
  • Savings are recorded whenever the final model is cheaper than the one the caller named; that's ordinary routing, not specific to a reroute.
  • Restrictions are per member and don't affect other members or your own key.
Member alert emails
  • Member alert to the member's account email: their spend, cap and percentage. Owner alert to yours, naming the member.
  • Each threshold fires at most once per member per 24 hours. If one request crosses both, only the 100% alert is sent.
  • No setup beyond setting the cap.
Deleting your account

Delete your account from the Profile page. Workspace owners must remove all members first, because members' requests run on the owner's provider keys. Members can delete their own account at any time.

Spend caps

  • Caps are enforced before a request is sent. Rouva reserves the request's worst-case cost and swaps it for the real cost once the provider reports usage, so a burst of requests can't run past the cap.
  • At the cap, requests get 429 with Retry-After until the cap resets on the 1st (UTC). The owner can raise it any time.
  • Near the cap, a request can be refused even when its real cost would have fit: lower max_tokens or shorten the prompt.
  • Capped keys can't use inputs whose cost isn't known up front (400, see Details).
  • Spend and caps use Rouva's pricing data and the token counts providers report, so they are close estimates — your provider's bill is the authoritative figure.
How the worst case is calculated

Rouva reserves the request's worst-case cost, calculated conservatively:

  • the prompt counted as one token per byte of the request JSON with images left out (well above its real token count), plus a flat 6,000 tokens per image and 1,000 tokens if any tools are present;
  • max_tokens of output, all at the model's listed price;
  • for Claude models, input priced at Anthropic's cache-write rate (1.25×, or 2× if your request sets 1-hour cache markers);
  • for OpenAI models that bill cache writes (GPT-5.6 and newer), input priced at the cache-write rate (1.25×);
  • for Qwen models with explicit caching, when the request carries cache_control markers, input priced at the model's cache-creation rate (Qwen Flash 1.26×, Qwen3.8 Flash 1.33×, Qwen3.7 Flash 1.27×, Qwen Plus 1.25×, Qwen3.7 Plus 1.25×);
  • for models whose provider charges more for long prompts (GPT-5.6, GPT-6, GPT-6.1 and GPT-6.2 above 272K tokens, Claude Haiku 5.5 above 100K, Grok 4.x from 200K, Gemini 2.5 Pro above 200K, Qwen Plus, Qwen3.7 Plus and Qwen Flash above 256K, Qwen3.7 Flash above 32K and again above 256K, MiniMax M3 above 512K), the long-context rates whenever the prompt's estimate reaches that size — for these listed models, the recorded cost of a request whose prompt reaches the tier uses those rates too;
  • for DeepSeek models, whose price halves outside DeepSeek's peak hours (01:00–04:00 and 06:00–10:00 UTC, Monday to Friday), the peak price — the recorded cost of a request that starts off-peak is half;
  • for reasoning models whose hidden reasoning isn't counted in max_tokens (Gemini and Alibaba Qwen), and for any model Rouva doesn't list from a provider other than OpenAI, Anthropic, Moonshot, Z.ai, MiniMax or xAI, an extra 32,768 output tokens for hidden reasoning;
  • for xAI Grok models, whose reasoning has no documented limit, output up to the model's whole context window (500K or 1M tokens), so near a cap Grok requests are refused sooner;
  • and the cost of a possible summarization call (see Request handling).

If a request ends without reported usage — for example a stream that is cut off, a timeout or a reset connection — the provider may still have billed it, so the worst-case reservation is kept until the cap resets at the start of the next month rather than released. If the worst case doesn't fit, the request gets 429 with Retry-After: 10. If Rouva can't check the cap (for example, a database error), the request is refused with 503 rather than sent unchecked.

Capped keys get 400 with an explanation for: document and file inputs (PDFs, URLs, file IDs), audio inputs, server-side tools (e.g. web search), models whose hidden reasoning Rouva can't limit (currently the Qwen3.8 Omni models, such as Qwen3.8 Omni Flash), and models with no known pricing.

Cost per customer

Tag each request with the ID of your customer and Rouva totals what each one costs you in AI.

HTTP (/api/gateway/messages, /v1/chat/completions or /api/gateway/run)
{
  "model": "gpt-6-luna",
  "messages": [{ "role": "user", "content": "Summarize this ticket" }],
  "metadata": { "customer_id": "acme" }
}
  • metadata.customer_id: a string up to 256 characters, such as your account ID or a domain.
  • The Spend page shows each customer's requests, spend, share and quality by month; Export CSV gives spend per customer per day.
  • Requests without one show as Untagged (a blank Customer ID in the CSV). On /run, every turn is tagged and counts as one request.
  • An owner's page includes teammates' requests; a teammate sees their own.
  • The ID is stored with the request's usage record and never sent to the model provider. Other metadata keys work as before.
SDK examples
Rouva SDK
await rouva.chat.completions.create({
  messages: [{ role: 'user', content: 'Summarize this ticket' }],
  metadata: { customer_id: account.id },
})
OpenAI SDK (Python), pointed at Rouva's /v1
client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Summarize this ticket"}],
    metadata={"customer_id": account.id},
)

Customer caps

  • Set: on the Spend page select customers → Set cap, or Cap a customer by ID before its first request. Owners only; no default caps.
  • Enforced like a key cap: the worst case is reserved first, and a capped customer gets 429 with X-Rouva-Refusal: customer_cap until the 1st (UTC), unless you raise the cap.
  • Counts your and your teammates' requests for that customer.
  • Alerts by email (and Slack, if connected) at 80% and 100%, once per customer and threshold each month.
  • As with key caps, a capped customer's requests can't use input or models whose cost can't be bounded (X-Rouva-Refusal: unbounded).

To set many caps from your app or CRM, call the API with a Rouva key (owners only): up to 500 per call, cap_usd: null removes one, and GET on the same address lists every cap with this month's spend.

PUT /api/customer-caps
curl -X PUT https://app.rouva.io/api/customer-caps \
  -H "Authorization: Bearer $ROUVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "caps": [
        { "customer_id": "acme",   "cap_usd": 20 },
        { "customer_id": "globex", "cap_usd": 50 },
        { "customer_id": "initech", "cap_usd": null }
      ] }'

Routing impact

The dashboard's Impact page shows what routing saved in a month and the quality it kept. It's shown to the workspace owner and counts members' requests too.

  • Saved: for each request, the cost on the model you requested minus the cost on the model Rouva used. Without a model, the comparison is the priciest model Rouva could have picked for the task. A pricier pick counts against the total.
  • Without routing: your spend plus what routing saved: what the same requests would have cost on the models requested.
  • Moved to a cheaper model: requests Rouva sent to a model other than the one requested, and cheaper. A cache or off-peak discount on the model you requested isn't counted.
  • Quality (in the headline): the average Quality Score (0–100, from Rouva's judge) on requests routed to a cheaper model, next to the rest. Only scored requests count.
  • Savings over the month: the running total, day by day (UTC).
  • By task and Top swaps: what each task type saved, and the model requested next to the cheaper one used, by money saved.

FOCUS CSV

Export FOCUS CSV at the foot of the Impact page gives the month's spend per UTC day, provider and model in FOCUS column names (BilledCost, ChargePeriodStart, ProviderName, SkuId, …), so FinOps tools can import it. Rouva's own columns start with x_Rouva: requests, input and output tokens, and savings.

  • Costs are Rouva's figures from each provider's list prices, not the provider's invoice. If your FinOps tool also imports your providers' bills, use this file for the split by model rather than adding both.
Alerts and integrations

Alert webhooks

Besides email and Slack, Rouva can POST each budget and cap alert to your own HTTPS endpoint as signed JSON.

  • Connect: Alerts → Webhook (owners). The signing secret is shown once, when you connect or rotate it, so copy it then.
  • Test: Send test delivers a webhook.test event.
  • Use it to page someone, post to another chat tool, turn a key off, or update your CRM through Zapier.
EventSent when
budget.threshold_reachedA provider's spend this month reaches your alert threshold for its budget (members' requests count). At most once per provider in 24 hours.
member_cap.threshold_reachedA member reaches 80% or 100% of their cap. At most once per member and threshold per day; only 100% when both are crossed.
customer_cap.threshold_reachedOne of your customers reaches 80% or 100% of its cap. Once per customer and threshold each month; only 100% when a check finds both crossed.
customer.usage_summaryDaily, 01:00–02:00 UTC, one per customer active the day before. Off until you turn on Daily customer summary.
webhook.testYou click Send test.
POST https://example.com/rouva-webhook
content-type: application/json
webhook-id: evt_4f1c2a9d0b8e47c3a6d51e2f90b7c8a1
webhook-timestamp: 1792641600
webhook-signature: v1,<base64 HMAC-SHA256>

{
  "id": "evt_4f1c2a9d0b8e47c3a6d51e2f90b7c8a1",
  "type": "budget.threshold_reached",
  "created_at": "2026-10-22T04:00:00.000Z",
  "data": {
    "provider": "openai",
    "provider_label": "OpenAI",
    "threshold_pct": 80,
    "spend_pct": 81.4,
    "spend_usd": 40.7,
    "budget_usd": 50,
    "since": "2026-10-01T00:00:00.000Z",
    "dashboard_url": "https://app.rouva.io/dashboard/providers"
  }
}
Event fields
  • member_cap.threshold_reached: member (id, email, name), threshold_pct, spend_pct, spend_usd, cap_usd, since, dashboard_url.
  • customer_cap.threshold_reached: customer_id (the ID your requests send), threshold_pct, spend_pct, spend_usd, cap_usd, since (the month start), dashboard_url.
  • since is when spend is counted from: the month start (UTC), or later when the provider key was added or the member joined this month.
Verifying the signature
  • Signed the Standard Webhooks way, so its libraries work.
  • webhook-signature is v1, plus the base64 HMAC-SHA256 of webhook-id.webhook-timestamp.body, keyed with the base64-decoded part of your secret after whsec_.
  • Check it against the raw body, before parsing, and reject timestamps more than five minutes old.
// npm install standardwebhooks
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.ROUVA_WEBHOOK_SECRET) // "whsec_…"

export async function POST(req) {
  const body = await req.text()
  let event
  try {
    // Throws on a bad signature or a timestamp more than 5 minutes off
    event = wh.verify(body, Object.fromEntries(req.headers))
  } catch {
    return new Response('invalid signature', { status: 401 })
  }
  if (event.type === 'budget.threshold_reached') {
    // event.data.provider, event.data.spend_usd, event.data.budget_usd …
  }
  return new Response(null, { status: 204 })
}
Delivery and retries
  • Any 2xx within 5 seconds counts as delivered. Anything else (another status, a timeout, a redirect, which isn't followed) is retried while the threshold is still crossed.
  • Alert checks run after each gateway request; after a failed delivery they skip your endpoint for 5 minutes (a successful Send test ends the pause).
  • A retry of the same alert has the same webhook-id (budget and member alerts: the same day; customer alerts: the same month and cap, so an alert after you change a customer's cap has a new id). Use it to drop repeats.
  • The URL must be HTTPS on a public host. Rouva checks it when you save it and before each delivery, and refuses localhost and private addresses.

Daily customer summary

One customer.usage_summary webhook event per customer per day, so your CRM can show what each account costs.

  • Turn on Daily customer summary under Alerts → Webhook.
  • Covers each customer that made requests on the previous UTC day, from the metadata.customer_id your requests send (see Cost per customer). Untagged requests aren't included.
  • Totals match the dashboard's Spend page.
{
  "id": "evt_9b2e7c41d0a84f6e8c3d5a1b2f4e6d80",
  "type": "customer.usage_summary",
  "created_at": "2026-10-28T01:04:12.000Z",
  "data": {
    "customer_id": "acme",
    "date": "2026-10-27",
    "requests": 412,
    "spend_usd": 3.184,
    "quality_score": 91,
    "month_to_date": {
      "since": "2026-10-01T00:00:00.000Z",
      "requests": 9310,
      "spend_usd": 71.52
    },
    "cap_usd": 100,
    "cap_used_pct": 71.5,
    "dashboard_url": "https://app.rouva.io/dashboard/spend?month=2026-10"
  }
}
Fields and retries
  • date is the UTC day summarized; spend_usd, requests and quality_score (0–100, average of the day's scored requests; null when none was scored) cover that day.
  • month_to_date runs through the end of that day. cap_usd and cap_used_pct are null when the customer has no cap.
  • Each customer and day has its own webhook-id. If a delivery fails, the next day's run picks up where it stopped (up to 3 days back) and may repeat a few events your endpoint already accepted, so use the id to drop repeats.
  • A repeat carries the figures as of when it's sent, so for a missed day cap_usd is the cap at that time.

Zapier

Send Rouva's events to HubSpot, Salesforce, Pipedrive or any app Zapier connects, with no code.

  • Rouva's Zapier app (private beta). Owners add it from Connect with Zapier on the dashboard's Integrations page (or Spend page) and connect it with a Rouva API key.
  • Triggers: Customer Cap Reached (80% or 100% of a customer's cap) and Daily Customer Usage (each customer's spend for the day before).
  • Actions: Set Customer Cap and Remove Customer Cap, so a CRM plan change can set the cap.
  • Example: when a customer reaches 80% of its cap, create a task for its account owner.
Without the app: a webhook Zap
  1. In Zapier, create a Zap with the trigger Webhooks by Zapier → Catch Hook, and copy its URL.
  2. In Rouva, open Alerts → Webhook, paste the URL and connect it. Click Send test so Zapier gets a sample event.
  3. Add a Filter step that continues only when type is customer_cap.threshold_reached (or the event you want).
  4. Add your CRM's action, such as HubSpot Create Task or Update Company, mapping data.customer_id, data.threshold_pct, data.spend_usd, data.cap_usd.
  • To find the CRM record, search on data.customer_id: store the same ID on the record (e.g. a custom property).
  • To keep a company's AI spend current, a second Zap filters on customer.usage_summary and runs Update Company with data.month_to_date.spend_usd (and data.quality_score, if you track it).
  • Catch Hook doesn't check Rouva's signature, so treat its URL as a secret. If it leaks, make a new trigger and connect the new URL.

OpenTelemetry export

A span for every request, sent to your tracing backend over OTLP/HTTP (JSON), so model calls sit next to the rest of your traces.

  • Set up: Integrations → OpenTelemetry export (owners): the endpoint, any headers your backend needs (usually an API key), and a service name (default rouva). Send test span checks it.
  • Join your traces: send a W3C traceparent header and Rouva's span becomes a child of yours. OpenTelemetry's HTTP instrumentation adds it for you.
  • No prompt or response text is ever sent.
  • Members' requests go to the owner's endpoint.
BackendEndpointHeader
Honeycombhttps://api.honeycomb.io/v1/tracesx-honeycomb-team: your-api-key
OpenTelemetry CollectorYour collector's OTLP/HTTP receiver over HTTPS, e.g. https://otel.example.com/v1/tracesWhatever your collector requires
What a span contains

One span per request-log row, named chat {model} (kind CLIENT), from when Rouva received the request until the provider's answer was complete. A failed provider call has an error status and error.type.

AttributeValue
gen_ai.operation.namechat
gen_ai.provider.name, gen_ai.systemThe provider that served the request
gen_ai.request.model, gen_ai.response.modelThe model you asked for and the one that answered
gen_ai.usage.input_tokens, gen_ai.usage.output_tokensToken counts as the provider reported them
gen_ai.response.id, gen_ai.response.finish_reasonsThe provider's response id and finish reason
rouva.request_idThe request's id (X-Rouva-Request-Id)
rouva.cost_usd, rouva.saved_usd, rouva.cost_finalCost, savings, and whether the cost is final (false when the provider's usage was incomplete)
rouva.route_reason, rouva.task_type, rouva.requested_modelWhy this model, the task type, and the model you named
rouva.quality_score, rouva.judge_statusThe quality score (0–1) when one was computed
rouva.session_id, rouva.member.idThe session (x-rouva-session-id), and the workspace member who sent it
rouva.metadata.*Your request's metadata fields (up to 20)
Details
  • A bare origin gets OTLP's default path, /v1/traces. Any backend that takes OTLP/HTTP with JSON works; a collector can forward to the ones that don't.
  • Header values are stored encrypted and never shown again. When you move the endpoint to another host, re-enter them: saved headers never follow it.
  • Without a traceparent, each request starts its own trace (a fallback retry, or every turn of a /run, shares it). One whose sampled flag is off is respected: nothing is exported. On /run, every turn is its own span in the same trace.
  • Spans are sent a few seconds after the response, once the quality score is recorded. If your endpoint fails, exports to it pause for a minute and the error shows on the Integrations page. Settings changes take up to a minute to apply everywhere.

Plans and limits

Every feature is on every plan. Plans differ in the requests they include each month, how many users they hold, how much history the dashboard keeps and how many requests are quality scored. Prices are on the pricing page.

PlanRequests a monthUsersHistoryQuality scoringPast the included requests
Free10,00017 daysNoneRefused until the 1st (UTC)
Starter50,000330 daysHalf of requests, sampled$10 per extra 100,000, not scored
Team100,0001090 daysEvery request$10 per extra 100,000, not scored
  • The owner's plan. Billing is on the workspace owner. Members run on the owner's plan, and their requests count toward it.
  • What counts. Requests are counted per calendar month (UTC). Not counted: replays from the 60-second duplicate cache (see Request handling), requests Rouva refuses before sending, and requests that fail on the provider's side: a 5xx, 429 or 408, a rejected provider key (401 / 403), a timeout or a dropped connection. Mistakes in the request that the provider rejects (such as 400 or 404) count, and so does a stream you cut off.
  • At the limit on Free. The next request gets 429 with X-Rouva-Refusal: plan_limit and a Retry-After of the seconds until the 1st (UTC). The error message says when requests resume and links to the Billing page. Paid plans are never refused (see Errors and refusals).
  • Extra requests on paid plans. Requests past Starter's or Team's included amount are charged per request, $10 per 100,000 ($0.0001 each), counted per calendar month (UTC) and billed after the month ends, monthly on annual plans too. A month is charged only when a paid subscription covered all of it, so requests made before subscribing or during a trial never are. The Billing page shows the extra requests and their cost so far. They aren't charged during a free trial or on a complimentary plan.
  • Usage. The owner gets an email at 80% and at 100% of the month's included requests, and the dashboard's sidebar shows the month's count.
  • Users. The owner plus members, with pending invites counted. Invites past the plan's users are refused. After a downgrade nobody is removed; new invites wait until there's room.
  • History. Requests older than the plan's history are hidden from the request log, the Spend page, exports and Cost lookup, never deleted: a plan with a longer history shows them again.
  • Quality scoring. An unscored request says why in its judge_status: skipped_plan on Free, sampled_out_plan outside Starter's half, skipped_overage past a paid plan's included requests.
Trials, founding rates and paying
  • Starter and Team start with a 30-day free trial, with no card needed, for accounts that haven't subscribed before. Without a card the account moves to Free when the trial ends, and nothing is charged.
  • Founding rates (Starter $19 a month, Team $69) are offered for a limited time after launch and kept for as long as the subscription stays active.
  • Annual billing is 10% off. Payments, invoices and cancelling are on Stripe's secure pages, opened from the dashboard's Billing page. Change plan on the same page: upgrades apply now (the difference is added to your next invoice), downgrades when the paid period ends. Cancelling doesn't refund the current period.

Ready to get started?

Create your account, connect a provider, and make your first routed request in minutes. Questions? See the FAQ.

Get started free →