Local API
Use the host-agent local OpenAI-compatible endpoints, model-profile readiness, and receipt APIs.
The local API is served by the host agent on the node machine. It is for local clients, setup flows, and router-signed dispatch into the node when configured.
Default base URL:
texthttp://127.0.0.1:8831
Endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /health | none | Local health check |
| GET | /v1/models | local key or setup/operator | List locally installed OpenAI-compatible models |
| POST | /v1/chat/completions | local key or router-signed | Run local OpenAI-compatible chat |
| POST | /v1/embeddings | local key | Generate embeddings (when the runtime serves an embedding model) |
| POST | /v1/images/generations | local key | Generate images (when the runtime serves an image model) |
| POST | /v1/audio/speech | local key | Synthesize speech (when the runtime serves an audio model) |
| POST | /v1/audio/transcriptions | local key | Transcribe audio (when the runtime serves an audio model) |
| POST | /v1/rerank | local key | Rerank documents (when the runtime serves a rerank model) |
| GET | /v1/model-profiles | setup/operator | Inspect local model profile readiness |
| GET | /v1/receipts | setup/operator | List recent local receipts |
| POST | /v1/receipts/submit | setup/operator | Submit a local receipt to the configured control plane |
The embeddings, image, audio, and rerank endpoints are served when the installed runtime and model support that modality (for example, LocalAI, or an MLX or llama.cpp model that provides it). They use the standard OpenAI-compatible request and response shapes.
List Local Models
bash: "${B3IQ_LOCAL_KEY_FILE:?set B3IQ_LOCAL_KEY_FILE}"B3IQ_LOCAL_BASE_URL="${B3IQ_LOCAL_BASE_URL:-http://127.0.0.1:8831}"cfg="$(mktemp)"chmod 600 "$cfg"trap 'rm -f "$cfg"' EXIT{ printf 'url = "%s/v1/models"\n' "${B3IQ_LOCAL_BASE_URL%/}" printf 'header = "Authorization: Bearer %s"\n' "$(sed -n '1p' "$B3IQ_LOCAL_KEY_FILE")"} > "$cfg"curl --fail --silent --show-error --config "$cfg"
Local Chat
bash: "${B3IQ_LOCAL_KEY_FILE:?set B3IQ_LOCAL_KEY_FILE}"B3IQ_LOCAL_BASE_URL="${B3IQ_LOCAL_BASE_URL:-http://127.0.0.1:8831}"cfg="$(mktemp)"chmod 600 "$cfg"trap 'rm -f "$cfg"' EXIT{ printf 'url = "%s/v1/chat/completions"\n' "${B3IQ_LOCAL_BASE_URL%/}" printf 'request = "POST"\n' printf 'header = "Authorization: Bearer %s"\n' "$(sed -n '1p' "$B3IQ_LOCAL_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": "Run a local B3IQ smoke reply." }], "stream": false}JSON
javascriptimport { readFileSync } from "node:fs";const baseURL = process.env.B3IQ_LOCAL_BASE_URL ?? "http://127.0.0.1:8831";const token = readFileSync(process.env.B3IQ_LOCAL_KEY_FILE, "utf8").trim();const response = await fetch(`${baseURL}/v1/chat/completions`, { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ model: "qwen3-8b", messages: [{ role: "user", content: "Run a local B3IQ smoke reply." }], stream: false })});console.log(await response.json());
Router-Signed Dispatch
The same local chat endpoint can accept router-signed requests when the host agent and control plane have matching HMAC secrets configured. Router-signed pooled-sync dispatch is a network workflow, not a normal local application credential.
Router-signed streaming is supported: the node runs the completion, records the signed receipt once generation finishes, then delivers the response as SSE like any other streamed chat completion.
Model Profiles
Use GET /v1/model-profiles in setup/operator context to inspect install state,
runtime kind, route tier, network eligibility, and benchmark-gated route
readiness. Runtime IDs are local-only and should not be copied into public
payloads.
Receipts
The local receipt endpoints let an operator inspect recent local receipts and submit the latest or a selected receipt to the configured control plane.
Receipts can include model ID, usage, node ID, billing metadata, and receipt hash. They must not expose raw prompts or outputs in public protocol payloads.