> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat completions — POST /v1/chat/completions

> POST /v1/chat/completions — generates replies from a message history. Accepts model, messages, stream, temperature. Returns a chat completion or SSE stream.

The chat completions endpoint is the primary way to run inference on Darkbloom. It is fully compatible with the OpenAI Chat Completions API, so any OpenAI SDK works by setting the base URL to `https://api.darkbloom.dev/v1`. The coordinator routes your request to a hardware-attested Apple Silicon provider, encrypts the request body with the provider's X25519 key before forwarding it, and returns the response through the standard OpenAI response shape.

Every response includes provider attestation headers so you can independently verify the hardware that served your request.

`POST /v1/responses` is an alias for the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses). The coordinator auto-detects whether the body uses `input` (Responses format) or `messages` (Chat Completions format) and routes through the same handler.

## Authentication

All inference endpoints require a Bearer token. Pass your API key in the `Authorization` header:

```
Authorization: Bearer eigeninference-...
```

Get your API key from the [Darkbloom console](https://darkbloom.dev).

## Request

<ParamField body="model" type="string" required>
  The model ID to use for this request. See [Models](/reference/models) for the list of available model IDs.

  Example: `"qwen3.5-27b-claude-opus-8bit"`
</ParamField>

<ParamField body="messages" type="object[]" required>
  The conversation history as an array of message objects. Each object must have a `role` and a `content` field.

  * `role` — `"system"`, `"user"`, or `"assistant"`
  * `content` — the message text (string)
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  When `true`, the response is delivered as a stream of Server-Sent Events (SSE). Each event carries a `data:` field with a JSON chunk. The stream ends with `data: [DONE]`.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens to generate. If not set, the coordinator injects a default of 8192 to bound the worst-case cost. Set this explicitly if you need longer generations.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between 0 and 2. Higher values make output more random; lower values make it more deterministic.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling parameter. The model considers only the tokens comprising the top `top_p` probability mass.
</ParamField>

<ParamField body="stop" type="string | string[]">
  One or more sequences at which generation stops. The stop sequence itself is not included in the output.
</ParamField>

<ParamField body="seed" type="integer">
  Fixed random seed for reproducible outputs. Two requests with the same seed and parameters will produce identical results when served by the same provider.
</ParamField>

## Response (non-streaming)

<ResponseField name="id" type="string">
  Unique identifier for the request.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"` for non-streaming responses.
</ResponseField>

<ResponseField name="choices" type="object[]">
  Array of completion choices. Standard requests return exactly one choice.

  <Expandable title="choice fields">
    <ResponseField name="choices[].message" type="object">
      The generated message.

      <Expandable title="message fields">
        <ResponseField name="choices[].message.role" type="string">
          Always `"assistant"`.
        </ResponseField>

        <ResponseField name="choices[].message.content" type="string">
          The generated text.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="choices[].finish_reason" type="string">
      Why generation stopped. `"stop"` means the model reached a natural end; `"length"` means `max_tokens` was reached.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token counts for the request.

  <Expandable title="usage fields">
    <ResponseField name="usage.prompt_tokens" type="integer">
      Tokens consumed by the input messages.
    </ResponseField>

    <ResponseField name="usage.completion_tokens" type="integer">
      Tokens generated in the response.
    </ResponseField>

    <ResponseField name="usage.total_tokens" type="integer">
      Sum of prompt and completion tokens.
    </ResponseField>
  </Expandable>
</ResponseField>

## Streaming

When `stream: true`, the response is a sequence of SSE events:

```
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"finish_reason":null}]}

data: [DONE]
```

Just before `[DONE]`, the coordinator may emit a final event carrying the provider's Secure Enclave signature over the response hash:

```json theme={null}
{"choices":[],"se_signature":"<base64>","response_hash":"<hex>"}
```

## Response headers

Every response (streaming and non-streaming) includes attestation headers that describe the provider that served the request.

| Header                        | Description                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `X-Provider-Attested`         | `"true"` if the provider passed the most recent challenge-response attestation cycle  |
| `X-Provider-Trust-Level`      | `"self_signed"` or `"hardware"` — the provider's verified trust level                 |
| `X-Provider-Chip`             | Apple Silicon chip name, e.g. `"Apple M3 Max"`                                        |
| `X-Provider-Id`               | Internal provider identifier                                                          |
| `X-Provider-Model`            | Mac hardware model identifier                                                         |
| `X-Provider-Serial`           | Provider device serial number                                                         |
| `X-Provider-Secure-Enclave`   | `"true"` if the provider has a Secure Enclave                                         |
| `X-Provider-Mda-Verified`     | `"true"` if Apple MDA hardware attestation was verified                               |
| `X-Attestation-Se-Public-Key` | Provider's Secure Enclave P-256 public key (base64)                                   |
| `X-Attestation-Device-Serial` | Device serial matching the attestation record                                         |
| `X-Inference-Job-ID`          | Job UUID for this request, useful for correlating with usage records (streaming only) |

## Examples

<CodeGroup>
  ```bash cURL (non-streaming) theme={null}
  curl https://api.darkbloom.dev/v1/chat/completions \
    -H "Authorization: Bearer eigeninference-..." \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3.5-27b-claude-opus-8bit",
      "messages": [
        {"role": "user", "content": "Explain what a Merkle tree is."}
      ],
      "max_tokens": 512
    }'
  ```

  ```bash cURL (streaming) theme={null}
  curl https://api.darkbloom.dev/v1/chat/completions \
    -H "Authorization: Bearer eigeninference-..." \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3.5-27b-claude-opus-8bit",
      "messages": [
        {"role": "user", "content": "Explain what a Merkle tree is."}
      ],
      "stream": true
    }'
  ```

  ```python Python (OpenAI SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.darkbloom.dev/v1",
      api_key="eigeninference-..."
  )

  response = client.chat.completions.create(
      model="qwen3.5-27b-claude-opus-8bit",
      messages=[
          {"role": "user", "content": "Explain what a Merkle tree is."}
      ],
      max_tokens=512,
  )

  print(response.choices[0].message.content)
  ```

  ```python Python (streaming) theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.darkbloom.dev/v1",
      api_key="eigeninference-..."
  )

  stream = client.chat.completions.create(
      model="qwen3.5-27b-claude-opus-8bit",
      messages=[
          {"role": "user", "content": "Explain what a Merkle tree is."}
      ],
      stream=True,
  )

  for chunk in stream:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="", flush=True)
  ```

  ```javascript Node.js (OpenAI SDK) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.darkbloom.dev/v1",
    apiKey: "eigeninference-...",
  });

  const response = await client.chat.completions.create({
    model: "qwen3.5-27b-claude-opus-8bit",
    messages: [
      { role: "user", content: "Explain what a Merkle tree is." },
    ],
    max_tokens: 512,
  });

  console.log(response.choices[0].message.content);
  ```

  ```javascript Node.js (streaming) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.darkbloom.dev/v1",
    apiKey: "eigeninference-...",
  });

  const stream = await client.chat.completions.create({
    model: "qwen3.5-27b-claude-opus-8bit",
    messages: [
      { role: "user", content: "Explain what a Merkle tree is." },
    ],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "id": "a3f1c2e7-84bb-4d9a-91f3-2b7e6d4a0c18",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "A Merkle tree is a hash-based data structure where every leaf node contains the hash of a data block, and every non-leaf node contains the hash of its child nodes..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 87,
    "total_tokens": 101
  }
}
```