> ## 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.

# 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:

```text
http://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 |

**Modality endpoints follow your runtime**

The embeddings, image, audio, and rerank endpoints are served when the installed
  runtime and model support that modality (for example, LocalAI, or a 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 curl
: "${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
```

```javascript local-chat.js
import { 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
dispatch is an owned-machine control-plane workflow, not a normal local
application credential. Retained pooled-sync compatibility does not create a
shared public serving pool.

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 diagnostic payloads or historical public records.