> ## 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 local OpenAI-compatible chat completion.

Local clients should use a `b3iq_local_` API key with the local chat scope. B3IQ router-signed requests are also accepted on this endpoint when the router HMAC headers are configured. Router-signed streaming is supported: the receipt is recorded when the stream completes and `receipt_hash` is delivered in the final SSE chunk's `b3iq` metadata. 

` POST /v1/chat/completions `

Run a local OpenAI-compatible chat completion.

Local clients should use a `b3iq_local_` API key with the local chat
scope. B3IQ router-signed requests are also accepted on this endpoint
when the router HMAC headers are configured. Router-signed streaming
is supported: the receipt is recorded when the stream completes and
`receipt_hash` is delivered in the final SSE chunk's `b3iq` metadata.


## Servers

- ` http://127.0.0.1:8831 ` — Default local host-agent listener.

## Authentication

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

### Alternative 1

- ` LocalBearer `: ` http `

  - HTTP scheme: ` bearer ` (b3iq_local)

  - Local API key with local chat scope.

### Alternative 2

- ` LocalAPIKeyHeader `: ` apiKey `

  - Credential: ` X-B3IQ-API-Key ` in ` header `

  - Alternate header for local API keys.

### Alternative 3

- ` SetupBearer `: ` http `

  - HTTP scheme: ` bearer `

  - Setup token before operator configuration, or an authenticated operator session outside this spec.

### Alternative 4

- ` RouterSignedHeaders `: ` apiKey `

  - Credential: ` X-B3IQ-Router-Signature ` in ` header `

  - Router HMAC signature headers are used only by B3IQ router dispatch.

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

      - ` role `: type ` string `

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

      - ` content `: type ` string ` — May be omitted or empty on an assistant tool-call turn or a tool-role result message.

      - ` name `: type ` string ` — Tool name on a tool-role message, or an optional participant name on a user/assistant message.

      - ` tool_calls `: type ` array ` — Assistant tool-call array (OpenAI shape: `[{id, type, function: {name, arguments}}]`), forwarded verbatim.

        - ` array item `: type ` object `

      - ` tool_call_id `: type ` string ` — Links a tool-role message back to the assistant tool call it answers.

  - ` max_tokens `: type ` integer `

    - minimum: ` 1 `

  - ` temperature `: type ` number `

  - ` stream `: type ` boolean `

    - default: ` false `

  - ` runtime_id `: type ` string ` — Optional local runtime override.

  - ` session_id `: type ` string ` — Optional local playground session ID; unavailable for router-signed requests.

  - ` tools `: type ` array ` — OpenAI-compatible tool/function definitions, forwarded verbatim to the runtime so agentic clients can drive tool-calling.

    - ` array item `: type ` object `

  - ` tool_choice `: type ` unknown ` — OpenAI-compatible tool_choice control (`"auto"`, `"none"`, or a specific tool-selector object), forwarded verbatim to the runtime.

## 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 `, ` usage `, ` b3iq `

  - ` id `: type ` string `

  - ` object `: type ` string `

    - enum: ` ["chat.completion"] `

  - ` created `: type ` integer `

  - ` model `: type ` string `

  - ` choices `: type ` array `

    - ` array item `: type ` object `

      - Required fields: ` index `, ` message `, ` finish_reason `

      - ` index `: type ` integer `

      - ` message `: type ` object `

        - Required fields: ` role `

        - ` role `: type ` string `

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

        - ` content `: type ` string ` — May be omitted or empty on an assistant tool-call turn or a tool-role result message.

        - ` name `: type ` string ` — Tool name on a tool-role message, or an optional participant name on a user/assistant message.

        - ` tool_calls `: type ` array ` — Assistant tool-call array (OpenAI shape: `[{id, type, function: {name, arguments}}]`), forwarded verbatim.

          - ` array item `: type ` object `

        - ` tool_call_id `: type ` string ` — Links a tool-role message back to the assistant tool call it answers.

      - ` finish_reason `: type ` string `

  - ` usage `: type ` object `

    - Required fields: ` prompt_tokens `, ` completion_tokens `, ` total_tokens `

    - ` prompt_tokens `: type ` integer `

    - ` completion_tokens `: type ` integer `

    - ` total_tokens `: type ` integer `

  - ` b3iq `: type ` object `

    - Required fields: ` runtime_id `, ` runtime_kind `, ` latency_ms `

    - ` runtime_id `: type ` string `

    - ` runtime_kind `: type ` string `

    - ` latency_ms `: type ` integer `

    - ` ttft_ms `: type ` integer `

    - ` session_id `: type ` string `

    - ` receipt_hash `: type ` string `

Response header ` X-B3IQ-Receipt-Hash ` — Receipt hash for paid router-signed non-streaming responses. Streaming responses instead deliver `receipt_hash` in the final SSE chunk's `b3iq` metadata.

- ` value `: type ` string `

Response header ` X-RateLimit-Limit ` — Present for local API-key requests.

- ` value `: type ` integer `

Response header ` X-RateLimit-Remaining ` — Present for local API-key requests.

- ` value `: type ` integer `

Response header ` X-RateLimit-Reset ` — Seconds until local API-key rate-limit reset.

- ` value `: type ` integer `

### ` default ` — B3IQ-native problem response.

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` error `

  - ` error `: type ` object `

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

    - ` status `: type ` integer `

    - ` title `: type ` string `

    - ` detail `: type ` string `

    - ` code `: type ` string ` — Stable B3IQ code when present. See docs/error-codes.md.

## Request examples

### cURL

```curl
curl -X POST 'http://127.0.0.1:8831/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "string",
  "messages": [
    {
      "role": "system",
      "content": "string",
      "name": "string",
      "tool_calls": [
        {}
      ],
      "tool_call_id": "string"
    }
  ],
  "max_tokens": 1,
  "temperature": 0,
  "stream": false,
  "runtime_id": "string",
  "session_id": "string",
  "tools": [
    {}
  ],
  "tool_choice": null
}'
```

### JavaScript

```javascript
const response = await fetch('http://127.0.0.1:8831/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",
        "name": "string",
        "tool_calls": [
          {}
        ],
        "tool_call_id": "string"
      }
    ],
    "max_tokens": 1,
    "temperature": 0,
    "stream": false,
    "runtime_id": "string",
    "session_id": "string",
    "tools": [
      {}
    ],
    "tool_choice": null
  })
});

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

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.post('http://127.0.0.1:8831/v1/chat/completions', headers=headers, json={
  "model": "string",
  "messages": [
    {
      "role": "system",
      "content": "string",
      "name": "string",
      "tool_calls": [
        {}
      ],
      "tool_call_id": "string"
    }
  ],
  "max_tokens": 1,
  "temperature": 0,
  "stream": false,
  "runtime_id": "string",
  "session_id": "string",
  "tools": [
    {}
  ],
  "tool_choice": null
})
print(response.json())
```