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.

Endpoint

POST https://api.bees.riif.com/v1/chat/completions

Standard OpenAI request body. Two headers:

Header	Meaning
`Authorization: Bearer <key>`	Your Bees key. One key; no provider accounts.
`X-Bees-Subtenant`	An opaque label for your own customer. Scopes the cache partition. Required if you serve more than one.

Isolation is strict and structural. Nothing is shared across your customers or across ours, and an answer produced under one system prompt or tool schema is never served to a request carrying a different one.

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

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.