Docs

An OpenAI-compatible endpoint. Change one base URL, handle one new finish_reason, and you are integrated. Model access is included -- you do not bring a provider account.

Endpoints

One gateway, two dialects. Keep the client library you already use. Copy the block for your client, change nothing else.

If your code uses Anthropic

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.bees.riif.com",
    api_key=os.environ["BEES_API_KEY"],
)

r = client.messages.create(
    model="claude-sonnet-4",
    max_tokens=1024,
    system="...",
    messages=[...],
    tools=[...],          # passed through, both directions
)

If your code uses OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="https://api.bees.riif.com/v1",
    api_key=os.environ["BEES_API_KEY"],
)

r = client.chat.completions.create(model="bees", messages=[...])

The two base URLs differ by a /v1, and it does not matter. Each SDK appends its own path, so the correct base differs. We accept both forms either way, so if you copy the wrong line it still works. Authentication is the same story: send x-api-key or Authorization: Bearer, whichever your client already sends.

The model field is not a request, and the response tells you the truth. We route to the models we operate, so passing claude-sonnet-4 does not select it. The model we return names the one that actually answered, never an echo of what you asked for.

Verify your setup

Two steps, in this order. The first costs nothing, so if it fails you know the problem is the key or the URL rather than anything downstream.

1. Check the key. No model runs, nothing is charged.

curl https://api.bees.riif.com/v1/usage \
  -H "Authorization: Bearer $BEES_API_KEY"

{
  "tenant": "acme",
  "requests": 0,
  "balance_usd": 250.00,
  "burn_per_day_usd": 0,
  "days_remaining": null
}

A 401 here means the key is wrong or revoked. Nothing else can be at fault yet, because no model has been asked to do anything.

2. Make one real request.

Anthropic:

curl https://api.bees.riif.com/v1/messages \
  -H "x-api-key: $BEES_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4","max_tokens":32,
       "messages":[{"role":"user","content":"Reply with exactly: hello from bees"}]}'

{
  "type": "message",
  "role": "assistant",
  "model": "Qwen/Qwen3.5-9B",
  "content": [{ "type": "text", "text": "hello from bees" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 21, "output_tokens": 4 }
}

OpenAI:

curl https://api.bees.riif.com/v1/chat/completions \
  -H "Authorization: Bearer $BEES_API_KEY" \
  -H "content-type: application/json" \
  -d '{"messages":[{"role":"user","content":"Reply with exactly: hello from bees"}]}'

Look at model in that response. It names what actually ran, not what you asked for. That is how you can always tell what is answering your traffic, without taking our word for it.

Rerun step 1 afterwards: requests will have moved and balance_usd will have gone down by a fraction of a cent. That confirms metering and billing agree with what you just did.

Policy

One extra body field selects how much work a cache miss does.

{
  "messages": [ ... ],
  "policy": "verified",     // passthrough | fast | verified
  "threshold": 0.70          // optional; you may raise it, not lower a clamped one
}

Response

Standard OpenAI response, plus an additive bees block. Existing integrations do not break, because they ignore what they do not read.

{
  "choices": [ ... ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0 },
  "bees": {
    "cached": true,
    "policy": "verified",
    "consensus_strength": 0.87,
    "threshold": 0.70,
    "provider_usage": [ ... ],      // as reported by YOUR provider
    "counterfactual_usd": 0.0241,   // what this would have cost without us
    "escalated": false
  }
}

Token counts are the provider's reported figures, never our estimate. If they ever fail to reconcile against your invoice, that is a bug on our side.

The refusal

When agreement falls below the effective threshold, you do not get a completion.

{
  "choices": [{
    "index": 0,
    "finish_reason": "low_consensus",
    "message": { "role": "assistant", "content": null }
  }],
  "bees": {
    "consensus_strength": 0.41,
    "threshold": 0.70,
    "cluster_count": 3,
    "clusters": [
      { "size": 2, "summary": "..." },
      { "size": 2, "summary": "..." },
      { "size": 1, "summary": "..." }
    ],
    "escalated": true
  }
}

The finish reason is deliberately a value your code has never seen, and content is null — a best guess handed over with a warning gets used. You get the competing positions so a reviewer can decide in seconds.

Spend caps

Caps are enforced before dispatch, from a deliberately pessimistic estimate. A cap checked after the money is spent is a report, not a cap.

HTTP 429
{
  "error": {
    "type": "spend_cap_exceeded",
    "limit_usd": 25.0,
    "would_spend_usd": 0.31,
    "subject": "provider_spend",
    "window": "day"
  }
}

Two ceilings: one on inference spend, one on our fees.

Pricing

A flat rate per call, quoted after the measurement period. Nothing is billed during passthrough.

Usage

GET /v1/usage?days=30
Authorization: Bearer <key>

Requests, refusals, spend and net savings — all computed from the same rows that drive billing, so the dashboard cannot drift from your invoice. Savings are quoted net of our fee.

Errors

Status	Meaning
401	Unknown key
429	A spend cap would be breached. Nothing was dispatched.
502	Your provider failed. Not billed.

Not in this version

Streaming. Send stream=false. A streaming request is refused with a clear message rather than hanging.

Consensus over tool calls. Requests carrying tools are served straight through. Two models choosing the same tool with different arguments is neither agreement nor disagreement, so we do not pretend to measure it.

No streaming yet. No shared cross-customer cache tier. No action gating — we score responses, not tool calls. Say if any of these blocks you and it moves up the list.