API Overview
B3IQ's endpoint-first developer surface: hosted gateway APIs, local host-agent APIs, private jobs, receipts, usage, and stable error codes.
B3IQ is endpoint-first. Developers call HTTP APIs directly. The official developer surface is endpoint behavior, OpenAPI specs, examples, stable error codes, and public protocol metadata.
B3IQ doesn't ship its own client library or adapter — the hosted gateway is
OpenAI-compatible, so the official openai SDK (Python and JavaScript) and
any OpenAI-compatible tooling work against it with just a base URL and key
swap. See OpenAI SDK Quickstart.
API Families
Point the official Python or JavaScript OpenAI SDK at the hosted gateway —
chat completions, streaming, and models.list().
Public /v1/api/models, /v1/api/stats, and /v1/api/pricing, plus
authenticated OpenAI-compatible /v1/api/chat/completions backed by B3IQ
router, metering, and receipt policy.
Local OpenAI-compatible endpoints and node companion APIs served at
http://127.0.0.1:8831 by default.
OpenAI-Compatible Endpoint Matrix
| Surface | Endpoint | Auth | Notes |
|---|---|---|---|
| Hosted metadata | https://b3iq.org/v1/api/models | None | Public OpenAI-compatible model list |
| Hosted metadata | https://b3iq.org/v1/api/stats | None | Public aggregate network stats |
| Hosted metadata | https://b3iq.org/v1/api/pricing | None | Public quote and node-payout policy |
| Hosted gateway | https://b3iq.org/v1/api/chat/completions | Hosted gateway key | Free routed inference on your own machines, with metering, receipts, and route policy |
| Local host agent | http://127.0.0.1:8831/v1/chat/completions | Local `b3iq_local_` key | Local machine inference through the host agent |
| Native private jobs | https://b3iq.org/v1/api/private-inference/jobs | Customer headers | B3IQ-native encrypted async work, not OpenAI-compatible |
Credential Separation
| Surface | Credential | Notes |
|---|---|---|
| Local host-agent chat | b3iq_local_ | Local-only scoped key created by the owner in the setup wizard |
| Hosted gateway chat | b3iq_gateway_ | Gateway key that carries account ownership and usage attribution |
| Native private jobs | customer headers | Customer ID and token headers for B3IQ-native job creation and settlement reads |
| Setup and local admin | owner session or setup token | Local operator UI and setup APIs, not normal application credentials |
| b3iq CLI and automation | b3iq_pat_ | Personal access token minted by `b3iq login` or Settings → CLI tokens; shown once, revocable |
Base URLs
bashexport B3IQ_GATEWAY_BASE_URL="https://b3iq.org/v1/api"export B3IQ_LOCAL_BASE_URL="http://127.0.0.1:8831"
Use the public hosted gateway base URL for unauthenticated metadata and authenticated hosted work. For local node work, use the host-agent URL on the machine running B3IQ.
Request Safety Pattern
Store keys in files
bashumask 077mkdir -p .secretscat > .secrets/b3iq-gateway-keycat > .secrets/b3iq-local-key
Pass auth through a short-lived config
Avoid placing bearer tokens directly in shell argv.
Send request bodies through stdin
This keeps examples readable and avoids local files that accidentally include prompts, outputs, or secret material.
OpenAPI Specs
Public Privacy Rule
Prompts, outputs, exact private routes, API keys, customer identity, local URLs, filesystem paths, raw request logs, raw tokens, and raw TEE quotes do not belong in public docs examples, public protocol payloads, or settlement metadata.