Run a free scan

Quickstart

Welcome! Get your first request through Recovea in under five minutes. You change exactly two things: the base URL and the API key. This guide uses the free tier in observe-only mode — no credit card required, and nothing about your traffic changes until you say so.

1. Point your client at Recovea

Recovea speaks the OpenAI wire protocol on /v1 and Anthropic's native protocol on /anthropic, so the official SDKs work unmodified. You just override the base URL.

Three provider paths, two base URLs. OpenAI models run on the OpenAI-compatible /v1 surface under their bare ids (gpt-4o). Anthropic runs natively on the /anthropic surface with the official Anthropic SDK. The long tail — Gemini, Llama, Mistral, DeepSeek, and everything else OpenRouter serves — runs on /v1 too, under OpenRouter's vendor/model ids (google/gemini-2.5-pro), exactly as listed by GET /v1/models; a bare non-OpenAI id on /v1 returns an honest 404 that names the id to use. Native surfaces for more providers (Google first) are planned. You never swap to a Recovea SDK — there isn't one; you keep your provider's standard client and just change the base URL.

# OpenAI via Recovea
from openai import OpenAI  # Recovea is OpenAI-compatible: any OpenAI client works

client = OpenAI(
    base_url="https://api.sandbox.recovea.ai/v1",  # point the client at Recovea
    api_key="rcv_live_…",                  # your Recovea key, not a provider key
)

// OpenAI via Recovea
import OpenAI from "openai"; // Recovea is OpenAI-compatible: any OpenAI client works

const client = new OpenAI({
  baseURL: "https://api.sandbox.recovea.ai/v1", // point the client at Recovea
  apiKey: process.env.RECOVEA_API_KEY, // your Recovea key, not a provider key
});

Env-var only (zero code change)

If your code already reads the standard OpenAI environment variables, you don't touch the code at all:

export OPENAI_BASE_URL="https://api.sandbox.recovea.ai/v1"
export OPENAI_API_KEY="rcv_live_…"

2. Send a request

You're viewing OpenAI examples. On the OpenAI-compatible /v1 surface the model string is the only thing you change: OpenAI ids run bare (gpt-4o), and everything OpenRouter serves runs under its vendor/model id (google/gemini-2.5-pro) on your connected OpenRouter key. You always call the stable OpenAI-compatible interface — so when OpenAI revises its own SDK, your code keeps working. (Anthropic also has its own native /anthropic surface — pick Anthropic above to see it.) That's the point.

resp = client.chat.completions.create(
    model="gpt-4o",  # OpenAI on the /v1 surface
    messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(resp.choices[0].message.content)

The response shape is identical to your provider's — Recovea never alters the response body. Recovea adds an x-request-id and an x-recovea-trace-id header so every call is auditable back to your cost ledger; on a /v1 exact-cache hit you'll also see x-recovea-cache: hit.

3. Smoke-test with curl

Run this before touching app code:

curl https://api.recovea.ai/v1/chat/completions \
  -H "Authorization: Bearer $RECOVEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

What happens underneath

Your request is metered against a frozen baseline and passed through a risk-ordered lever pipeline. The levers serving traffic today are exact-response caching and in-flight dedup (identical concurrent requests coalesce onto one upstream call); model routing runs in shadow only for now and is planned to go live once its non-inferiority gate clears. Quality-affecting levers are continuously shadow-tested against that non-inferiority gate off the hot path — the shadow evaluation never blocks or alters your response. (Levers act on the /v1 surface; the /anthropic surface is metering-only today.)

If anything in Recovea's layer fails, the request flows straight through to your provider on your own key. It's reversible in one line: point your base URL back to your provider.

Did your first request fail?

Sometimes a request that works against your provider directly fails through Recovea at first. The most common causes, in order:

  1. You sent a provider key instead of a Recovea key. The Authorization header needs your rcv_live_… key; your provider key is stored in the dashboard and used upstream. A provider key here returns 401 with code: "invalid_api_key".
  2. No provider key is connected. Recovea signs the upstream call with your provider key — if none is connected for the provider that serves your model (OpenAI, Anthropic, or OpenRouter), you'll get a 403 permission_error with code: "no_provider_key" naming the provider you need. Add one in Settings → Connections & Keys in the dashboard, then retry.
  3. The base URL is missing its suffix. It's https://api.recovea.ai/v1 for OpenAI-compatible clients and https://api.recovea.ai/anthropic for the Anthropic SDK — without the suffix, SDK paths resolve to 404s.
  4. A bare non-OpenAI model id on /v1. Claude/Gemini/Llama ids run on /v1 only as their vendor/model id — the 404 message names the exact id to use, and GET /v1/models lists every invocable id. (Claude also runs natively on /anthropic.)

Still stuck? Every response carries an x-recovea-trace-id header — email it to support@recovea.ai and we can see exactly what happened to that request. We can help with anything in Recovea's layer; for issues inside your provider account (billing, quota, model access), your provider's console is the right place, and we'll say so rather than guess.

Next