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

# Run a chat completion from the apex OpenAI base URL.

Identical contract to `/v1/api/chat/completions`, served at the apex so `https://b3iq.org/v1` is the corresponding OpenAI SDK base URL. The Authorization header is forwarded to the control plane verbatim; auth, quotas and rate limits are enforced there. 

` POST /v1/chat/completions `

Run a chat completion from the apex OpenAI base URL.

Identical contract to `/v1/api/chat/completions`, served at the apex so
`https://b3iq.org/v1` is the corresponding OpenAI SDK base URL. The
Authorization header is forwarded to the control plane verbatim; auth,
quotas and rate limits are enforced there.


## Servers

- ` https://b3iq.org ` — Apex-fronted OpenAI base URL.

## Authentication

The operation accepts these alternatives. Schemes within one alternative are required together.

### Alternative 1

- ` HostedGatewayBearer `: ` http `

  - HTTP scheme: ` bearer ` (b3iq_gateway)

  - Scoped hosted gateway key. `gateway:chat` is required for chat; `gateway:models` is optional for the own-machines-scoped model list.

## Request body (required)

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` model `, ` messages `

  - ` model `: type ` string `

  - ` messages `: type ` array `

    - ` array item `: type ` object `

      - Required fields: ` role `, ` content `

      - ` role `: type ` string `

        - enum: ` ["system","user","assistant","tool"] `

      - ` content `: type ` unknown `

        - ` oneOf alternative 1 `: type ` string `

        - ` oneOf alternative 2 `: type ` array `

          - ` array item `: type ` object `

  - ` max_tokens `: type ` integer `

    - minimum: ` 1 `

  - ` temperature `: type ` number `

  - ` top_p `: type ` number `

  - ` stop `: type ` unknown `

    - ` oneOf alternative 1 `: type ` string `

    - ` oneOf alternative 2 `: type ` array `

      - ` array item `: type ` string `

  - ` stream `: type ` boolean `

    - default: ` false `

  - ` n `: type ` integer ` — B3IQ currently rejects `n > 1`.

    - minimum: ` 1 `

    - maximum: ` 1 `

  - ` b3iq `: type ` object ` — Router policy metadata consumed by B3IQ and stripped before node dispatch.

    - ` model_profile_id `: type ` string `

    - ` job_id `: type ` string `

    - ` max_price_wei `: type ` string `

    - ` dispatch_mode `: type ` string ` — Hosted chat rejects `private_job`.

      - enum: ` ["pooled_sync"] `

    - ` mixture `: type ` object ` — Mixture of Experts: fan the prompt out to several expert models and return one combined answer. Experts run in parallel and each is routed through normal B3IQ policy; experts cannot pin nodes.

      - Required fields: ` strategy `, ` experts `

      - ` strategy `: type ` string ` — synthesize combines expert answers with an aggregator model; vote returns the weighted-plurality answer; weighted returns the highest-weight successful expert answer.

        - enum: ` ["synthesize","vote","weighted"] `

      - ` experts `: type ` array ` — Capped by an operator-configured limit (default 4 experts; the aggregator is not counted).

        - ` array item `: type ` object `

          - Required fields: ` model `

          - ` model `: type ` string ` — Model id from GET /v1/api/models.

          - ` weight `: type ` number ` — Vote pooling / selection weight.

            - default: ` 1 `

      - ` aggregator `: type ` object ` — Required for the synthesize strategy; ignored otherwise.

        - Required fields: ` model `

        - ` model `: type ` string `

      - ` min_experts `: type ` integer ` — Quorum of experts that must succeed. Defaults to half the experts, rounded up, for vote; otherwise 1.

        - minimum: ` 1 `

      - ` max_price_wei `: type ` string ` — Aggregate price cap across every sub-call (experts plus aggregator); checked before any node is dispatched.

## Responses

### ` 200 ` — Chat completion response, or SSE stream when `stream` is true and allowed.

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` id `, ` object `, ` created `, ` model `, ` choices `

  - ` id `: type ` string `

  - ` object `: type ` string `

  - ` created `: type ` integer `

  - ` model `: type ` string `

  - ` choices `: type ` array `

    - ` array item `: type ` object `

  - ` usage `: type ` object `

    - ` prompt_tokens `: type ` integer `

    - ` completion_tokens `: type ` integer `

    - ` total_tokens `: type ` integer `

  - ` b3iq `: type ` object `

    - ` runtime_id `: type ` string `

    - ` runtime_kind `: type ` string `

    - ` latency_ms `: type ` integer `

    - ` ttft_ms `: type ` integer `

    - ` receipt_hash `: type ` string `

    - ` request_id `: type ` string `

    - ` mixture `: type ` object ` — Present when the request carried b3iq.mixture. Metadata-only trace of the fan-out — never expert or aggregator text.

      - ` strategy `: type ` string `

      - ` degraded `: type ` boolean ` — True when the mixture completed with a partial failure — one or more sub-calls did not succeed, or the synthesize aggregator failed and the answer fell back to the top-weighted surviving expert.

      - ` experts `: type ` array `

        - ` array item `: type ` object ` — Metadata-only trace of one mixture sub-call. Never contains answer text.

          - ` role `: type ` string `

            - enum: ` ["expert","aggregator"] `

          - ` model `: type ` string `

          - ` status `: type ` string ` — ok, no_node, upstream_error, billing_declined, or (defensively) error.

          - ` node_id `: type ` string `

          - ` usage `: type ` object `

            - ` total_tokens `: type ` integer `

### ` default ` — OpenAI-compatible error with B3IQ metadata.

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

    - Required fields: ` message `, ` type `, ` code `, ` b3iq `

    - ` message `: type ` string `

    - ` type `: type ` string `

    - ` param `: type ` unknown ` — A string value or null.

      - ` anyOf alternative 1 `: type ` string `

      - ` anyOf alternative 2 `: type ` null `

    - ` code `: type ` string `

    - ` b3iq `: type ` object `

      - Required fields: ` status `, ` title `, ` detail `, ` code `

      - ` status `: type ` integer `

      - ` title `: type ` string `

      - ` detail `: type ` string `

      - ` code `: type ` string `

      - ` job_id `: type ` string `

      - ` billing_lookup `: type ` string `

      - ` idempotency_status `: type ` string `

## Request examples

### cURL

```curl
curl -X POST 'https://b3iq.org/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "string",
  "messages": [
    {
      "role": "system",
      "content": "string"
    }
  ],
  "max_tokens": 1,
  "temperature": 0,
  "top_p": 0,
  "stop": "string",
  "stream": false,
  "n": 1,
  "b3iq": {
    "model_profile_id": "string",
    "job_id": "string",
    "max_price_wei": "string",
    "dispatch_mode": "pooled_sync",
    "mixture": {
      "strategy": "synthesize",
      "experts": [
        {
          "model": "string",
          "weight": 1
        }
      ],
      "aggregator": {
        "model": "string"
      },
      "min_experts": 1,
      "max_price_wei": "string"
    }
  }
}'
```

### JavaScript

```javascript
const response = await fetch('https://b3iq.org/v1/chat/completions', {
  method: 'POST',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "string",
    "messages": [
      {
        "role": "system",
        "content": "string"
      }
    ],
    "max_tokens": 1,
    "temperature": 0,
    "top_p": 0,
    "stop": "string",
    "stream": false,
    "n": 1,
    "b3iq": {
      "model_profile_id": "string",
      "job_id": "string",
      "max_price_wei": "string",
      "dispatch_mode": "pooled_sync",
      "mixture": {
        "strategy": "synthesize",
        "experts": [
          {
            "model": "string",
            "weight": 1
          }
        ],
        "aggregator": {
          "model": "string"
        },
        "min_experts": 1,
        "max_price_wei": "string"
      }
    }
  })
});

const data = await response.json();
console.log(data);
```