Revl Gateway documentation

How BYOK works

BYOK means bring your own key. The gateway holds no model-provider credentials. Every request carries two keys, and they do different jobs.

• Your provider API key travels in that provider's standard header: x-api-key for Anthropic, Authorization: Bearer for OpenAI. The gateway forwards it upstream for that one request. It is never written to storage, never logged, and never used for any other caller.
• Your Revl key (rvl_live_ followed by 32 to 128 URL-safe characters) travels in X-Revl-Key. It only identifies you to the gateway, which stores only the key's SHA-256 digest. It is never forwarded upstream.

Revl AI does not resell, sublicense, pool or share model-provider API access. Every request is authenticated to Anthropic or OpenAI with your own API key, under your own provider account and billing and that provider's terms and usage policies. Revl charges only for the gateway, never for model usage.

API keys only. OAuth and consumer subscription tokens are rejected; only provider API keys are accepted. On the Anthropic route, a request that carries an Authorization header and no x-api-key is rejected with 400 revl_oauth_not_supported.

Quickstart

Keep the SDK you already use. Change the base URL, pass your own provider key as usual, and add one header.

1. Set your keys

You need a Revl key and your own provider API key. The hosted gateway is invite-only, so a hosted Revl key comes with an invitation from the waitlist. If you self-host, you create one yourself. Export the keys so they never appear in code:

export REVL_API_KEY="rvl_live_your_gateway_key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"   # if you call Anthropic
export OPENAI_API_KEY="your-openai-api-key"         # if you call OpenAI

2. Send a request

pip install anthropic

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.proxyrevlvay.com",
    api_key=os.environ["ANTHROPIC_API_KEY"],  # your own Anthropic API key
    default_headers={"X-Revl-Key": os.environ["REVL_API_KEY"]},
)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.proxyrevlvay.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],  # your own OpenAI API key
    default_headers={"X-Revl-Key": os.environ["REVL_API_KEY"]},
)

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(completion.choices[0].message.content)

npm install @anthropic-ai/sdk

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.proxyrevlvay.com",
  apiKey: process.env.ANTHROPIC_API_KEY, // your own Anthropic API key
  defaultHeaders: { "X-Revl-Key": process.env.REVL_API_KEY },
});

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.proxyrevlvay.com/v1",
  apiKey: process.env.OPENAI_API_KEY, // your own OpenAI API key
  defaultHeaders: { "X-Revl-Key": process.env.REVL_API_KEY },
});

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

console.log(completion.choices[0].message.content);

# Anthropic Messages API
curl https://api.proxyrevlvay.com/v1/messages \
  -H "X-Revl-Key: $REVL_API_KEY" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 16000,
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

# OpenAI Chat Completions API
curl https://api.proxyrevlvay.com/v1/chat/completions \
  -H "X-Revl-Key: $REVL_API_KEY" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

• Self-hosting? Replace https://api.proxyrevlvay.com with your own Worker URL.
• The Node.js samples are ES modules that use top-level await. Save them with the .mjs extension.
• To see what the gateway did, read the X-Revl-* response headers. With cURL, add -i.

Endpoints

There is no translation layer. OpenAI-format requests go to OpenAI and Anthropic-format requests go to Anthropic. The body is forwarded unchanged unless you turn on masking. On the Anthropic route, the anthropic-version and anthropic-beta request headers are forwarded unchanged.

Request headers reach the provider by allow-list only: content-type, accept, user-agent, x-stainless-*, your provider key header, and openai-organization and openai-project on the OpenAI route. Cookies, every X-Revl-* header and any other client header are dropped, and the query string is not forwarded. A JWT-shaped bearer token on the OpenAI route, or an x-api-key that starts with sk-ant-oat, is rejected with 400 revl_oauth_not_supported.

Request options

Every option is an optional request header. X-Revl-Key and every other X-Revl-* request header are consumed by the gateway and are never forwarded upstream.

An invalid value returns 400 revl_bad_request naming the header.

Example: caching and masking on every request

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.proxyrevlvay.com",
    api_key=os.environ["ANTHROPIC_API_KEY"],
    default_headers={
        "X-Revl-Key": os.environ["REVL_API_KEY"],
        "X-Revl-Cache": "exact",        # cache identical requests
        "X-Revl-Cache-TTL": "600",      # keep entries for 10 minutes
        "X-Revl-Mask": "pii,secrets",   # mask before the request leaves the gateway
    },
)

To set an option for a single call instead, send the header with that request: extra_headers in the Python SDKs, the headers request option in the JavaScript SDKs.

Response headers

Added to every proxied response.

The upstream status code and body are returned unchanged, including upstream error responses, so each SDK's own error handling keeps working. set-cookie and hop-by-hop headers are dropped from the upstream response.

Caching

Send X-Revl-Cache: exact to cache a response. Matching is exact, not semantic. X-Revl-Cache-TTL sets how long an entry is kept. A hit returns X-Revl-Cache-Status: HIT and X-Revl-Upstream-Ms: 0.

With masking on, the key is computed over the masked body and the stored response is the upstream response before rehydration. On a hit, the response is rehydrated with the current request's mapping. Two prompts that differ only in masked values therefore share one cache entry, which is safe because the provider never saw the values.

Semantic caching: planned design

Roadmap. Not available in v0.1. Exact matching only helps when two requests are identical after canonicalisation. The planned semantic layer reuses a response when a new prompt means the same thing as an earlier one. This is the design we intend to build, published so you can review it before it ships. It may change.

1. Embed. The final user turn, after masking, is turned into a vector by an embedding model. The system prompt, model name, tools and sampling parameters are not embedded. They are hashed into a strict context key, so a hit can only come from a request with the same instructions and settings.
2. Search. The vector is looked up in an index partitioned by tenant, context key and the hash of the provider key. Tenants and provider accounts never share a partition.
3. Decide. The nearest neighbour is used only above a similarity threshold the caller sets per request. Below it, the request goes upstream and the new response is indexed.
4. Report. A semantic hit gets its own cache status and the similarity score in the response headers, so every reused answer can be audited.

Known limit: semantic reuse can return the answer to a question that only looks similar. It is unsuitable where a small change in wording matters, such as amounts, names or negation. For that reason it will be opt-in per request, with the exact-match cache checked first.

Masking

Send X-Revl-Mask with pii, secrets or pii,secrets. Matches are replaced with placeholders before the request leaves the gateway, and placeholders in the response are replaced with your original values.

Detectors

Where it applies

Masking is not applied to tool definitions, tool call arguments, or image and document data. It cannot be combined with streaming in v0.1.

Placeholders and rehydration

Placeholders look like <EMAIL_1>, <PHONE_1>, <CARD_1>, <IP_1> and <SECRET_1>. The same value gets the same placeholder within one request. The mapping exists only in memory for the duration of the request. The X-Revl-Masked response header reports the number of distinct values masked.

Streaming

Set "stream": true in the body as you normally would.

• The upstream response is passed through unbuffered.
• Streamed responses are not cached. X-Revl-Cache-Status is BYPASS.
• Masking with streaming is not supported in v0.1: 400 revl_mask_stream_unsupported.
• Retries apply only before the first upstream byte.

Rate limits

The gateway limits requests per tenant through the Workers rate limiting binding RATE_LIMITER. The default is 60 requests per 60 seconds, set in wrangler.jsonc. Over the limit you get 429 revl_rate_limited with Retry-After: 60. If the binding is absent, the gateway does not rate limit.

This is separate from your provider's own limits. A provider 429 passes through unchanged, while a gateway 429 has an error type that starts with revl_.

Errors

Every error the gateway itself produces has this shape and carries an X-Revl-Request-Id header. Messages never contain key material.

{"error": {"type": "revl_<code>", "message": "<human readable>"}}

Provider errors are not rewritten. The upstream status code and body pass through unchanged.

Self-hosting

The core runs as a Cloudflare Worker with two KV namespaces. You need a Cloudflare account and Node.js. The source is on GitHub. The commands below clone it and deploy the gateway directory.

# 0. Get the source
git clone https://github.com/trunghuynhnova/revl-ai-gateway.git
cd revl-ai-gateway/gateway

# 1. Install dependencies, sign in to Cloudflare
npm install
npx wrangler login

# 2. Create the two KV namespaces. Each command prints an id.
npx wrangler kv namespace create KEYS
npx wrangler kv namespace create CACHE

# 3. Put each id in the matching "kv_namespaces" entry in wrangler.jsonc, then deploy
npx wrangler deploy

# 4. Create a gateway key. The script prints the key once, and the command that stores its SHA-256 digest.
node scripts/create-key.mjs --id my-team --label "first key"
# Run the "npx wrangler kv key put ..." command it prints, then send the key as X-Revl-Key.

Check the deployment with GET /healthz, which returns {"ok":true,"version":"0.1.0"}. Then follow the quickstart.

Data handling

What the core stores and logs, and what it does not.

This describes the open-source core. This website collects waitlist email addresses only; see the Privacy Policy.

Available now and roadmap

Roadmap items are not built yet and are in no committed order.

Found something on this page that does not match what the gateway does? Tell us at founder@proxyrevlvay.com.