> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3iq.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Gateway

Call B3IQ hosted OpenAI-compatible endpoints with gateway keys, own-account routing, receipts, and streaming metadata.

The hosted gateway exposes OpenAI-compatible HTTP endpoints backed by B3IQ
router policy. Inference is **free**: your keys route to the machines on your
own account, the gateway enforces customer policy and quotas, and it records
receipt metadata without storing raw prompts or outputs in the control plane.

Use `https://b3iq.org/v1/api` as the public gateway base URL for application
traffic.

**Using the OpenAI SDK?**

The endpoints below are also reachable through the official `openai`
  Python/JavaScript SDK with a `base_url`/`api_key` swap. No raw HTTP required.
  See the [OpenAI SDK Quickstart](/guides/openai-sdk-quickstart).

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| ` GET ` | ` /v1/api/models ` | List models available to your gateway key on your own machines; anonymous calls return an empty list |
| ` GET ` | ` /v1/api/stats ` | Read public aggregate network stats without auth |
| ` GET ` | ` /v1/api/pricing ` | Read retained settlement-policy metadata; not a machine quote or a hosted inference rate |
| ` POST ` | ` /v1/api/chat/completions ` | Run a hosted OpenAI-compatible chat completion through B3IQ route policy |
| ` GET ` | ` /v1/api/receipts/{receipt_hash} ` | Read public-safe receipt evidence |

**Modality endpoints are local for now**

This public `/v1/api` facade documents chat. For embeddings, image generation,
  audio, or rerank, use the [local host-agent API](/developers/local-api) on a
  machine whose installed runtime serves that modality. Do not assume that an
  endpoint supported by a runtime is exposed through every public base URL.

**Pick a model id from your machines**

The `model` field takes an id returned by `GET /v1/api/models`. Called with
  your gateway key, that list is exactly the models the machines on your
  account serve right now. Anything on it can dispatch, and anything missing
  would fail with `no_eligible_nodes`. The examples below use a representative
  id (`qwen3-8b`); always list the live models first, since the set changes as
  your machines come and go.

## List models

```bash
: "${B3IQ_GATEWAY_BASE_URL:?set B3IQ_GATEWAY_BASE_URL}"
: "${B3IQ_GATEWAY_KEY_FILE:?set B3IQ_GATEWAY_KEY_FILE}"

cfg="$(mktemp)"
chmod 600 "$cfg"
trap 'rm -f "$cfg"' EXIT
{
  printf 'url = "%s/models"\n' "${B3IQ_GATEWAY_BASE_URL%/}"
  printf 'header = "Authorization: Bearer %s"\n' "$(sed -n '1p' "$B3IQ_GATEWAY_KEY_FILE")"
} > "$cfg"

curl --fail --silent --show-error --config "$cfg"
```

`/v1/api/models` returns the models available to the authenticated account's
machines. The key's node scope, account policy, machine mode, and current route
health can narrow that list. Calls without an owner-scoped key return a valid
OpenAI list with `data: []`; they do not expose another customer's models.
The authenticated response is uncached. List models before calling chat and
handle a route becoming unavailable between the two requests.

## Public metadata and compatibility

`/v1/api/stats` returns public aggregate state. `/v1/api/pricing` is retained
settlement-policy metadata for older integrations. It is not the price of a
machine, a public GPU rental offer, or a per-token charge for your gateway key.
Use the [machine catalog](https://b3iq.org/machines) for current configurations
and commercial pricing. Inference through your own gateway key carries no
per-request charge.

The `/v1/models` and `/v1/chat/completions` aliases have the same ownership
boundary. SDK clients using those aliases set their base URL to
`https://b3iq.org/v1`. `/openrouter/models` is retired; do not use it for
customer discovery or infer available capacity from its existence in an old
integration.

## Chat completion

```bash curl
: "${B3IQ_GATEWAY_BASE_URL:?set B3IQ_GATEWAY_BASE_URL}"
: "${B3IQ_GATEWAY_KEY_FILE:?set B3IQ_GATEWAY_KEY_FILE}"

cfg="$(mktemp)"
chmod 600 "$cfg"
trap 'rm -f "$cfg"' EXIT
{
  printf 'url = "%s/chat/completions"\n' "${B3IQ_GATEWAY_BASE_URL%/}"
  printf 'request = "POST"\n'
  printf 'header = "Authorization: Bearer %s"\n' "$(sed -n '1p' "$B3IQ_GATEWAY_KEY_FILE")"
  printf 'header = "Content-Type: application/json"\n'
} > "$cfg"

curl --fail --silent --show-error --config "$cfg" --data-binary @- <<'JSON'
{
  "model": "qwen3-8b",
  "messages": [{ "role": "user", "content": "Say hello from B3IQ." }],
  "max_tokens": 64
}
JSON
```

```javascript fetch.js
import { readFileSync } from "node:fs";

const baseURL = process.env.B3IQ_GATEWAY_BASE_URL;
const token = readFileSync(process.env.B3IQ_GATEWAY_KEY_FILE, "utf8").trim();

const response = await fetch(`${baseURL}/chat/completions`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${token}`,
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "qwen3-8b",
    messages: [{ role: "user", content: "Say hello from B3IQ." }],
    max_tokens: 64
  })
});

console.log(await response.json());
```

**Blend several models in one request**

The same endpoint can fan a prompt out to several models and return one
  combined answer. Attach a `b3iq.mixture` object. See
  [Mixture of Experts](/developers/mixture-of-experts).

## Streaming

Set `stream: true` to request SSE streaming. Hosted streaming proxies the
selected node stream while parsing final usage and `b3iq.receipt_hash`
metadata for usage metering and receipt settlement.

```json
{
  "model": "qwen3-8b",
  "messages": [{ "role": "user", "content": "Stream a short response." }],
  "stream": true
}
```

## Routing and policy

A request passes three gates, in order, before it runs:

1. **Key validity**: the gateway key must be active, unexpired, and carry the
   required scope and a usable customer identity.
2. **Rate limits and quota**: per-key and per-account rate limits, and the
   account's daily token quota (default uncapped), are enforced next.
3. **Own-account routing**: the request dispatches only to a machine on your
   account that is online and serving the requested model. When none can serve
   it, the request fails closed with `no_eligible_nodes`.

Hosted chat can also fail closed when the model or route tier is outside your
policy, or when an incident control pauses a route class, node, or payout path.

See [Errors](/developers/errors) for stable machine codes, and
[Usage & Quotas](/developers/usage-and-quotas) for metering, rate limits, and
the token quota.

## Headers

| Header | Direction | Description |
| --- | --- | --- |
| ` Authorization ` | Request | Bearer hosted gateway key |
| ` Idempotency-Key ` | Request | Accepted for compatibility and forwarded to the selected node. B3IQ does not deduplicate on it. |
| ` X-B3IQ-Router-Dispatch-Mode ` | Response | Routed response dispatch mode |
| ` X-B3IQ-Router-Node-ID ` | Response | Selected node ID when policy exposes it |
| ` X-B3IQ-Receipt-Hash ` | Response | Receipt hash returned by the selected node |

**Do not mix customer credentials**

Customer-owned gateway keys carry account ownership and usage attribution. Do
  not also send raw customer headers with those keys unless an operator smoke
  path explicitly requires it.