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

# Chat Completions – Streaming, Tools, and Structured Output

> Generate chat responses with the Boole AI chat completions endpoint — covering request parameters, streaming, tool calls, and structured JSON output.

The `/v1/chat/completions` endpoint generates a response for a conversation. It supports streaming via SSE, tool/function calls, and structured JSON output. It is the primary endpoint for all chat-based interactions and the recommended choice for new integrations.

## Endpoint

```
POST https://api.boole.dev/v1/chat/completions
```

## Request Body

<ParamField body="model" type="string" required>
  Model slug to use for the request, e.g. `llama-3.3-70b-instruct`. See [Models](/api-reference/models) for all available slugs.
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects that make up the conversation. Each object contains:

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

<ParamField body="stream" type="boolean">
  When `true`, responses are streamed as server-sent events (SSE). The stream ends with `data: [DONE]`. Default: `false`.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between `0` and `2`. Lower values produce more deterministic output; higher values increase creativity. Default: `1`.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens to generate in the response. If omitted, the model generates until it reaches a natural stopping point or its context limit.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling probability mass. Only tokens comprising the top `top_p` probability are considered. Default: `1`.
</ParamField>

<ParamField body="stop" type="string | array">
  One or more sequences at which generation stops. The model halts as soon as any sequence in the list is encountered.
</ParamField>

<ParamField body="tools" type="array">
  List of tools the model may call. Each entry has `type: "function"` and a `function` object containing `name`, `description`, and a JSON Schema `parameters` object.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls whether and how tools are used. Accepts `"auto"` (model decides), `"none"` (no tool calls), or an object targeting a specific function:

  ```json theme={null}
  {"type": "function", "function": {"name": "my_function"}}
  ```
</ParamField>

<ParamField body="response_format" type="object">
  Set to `{"type": "json_object"}` to enable JSON mode. The model is constrained to emit valid JSON.
</ParamField>

<ParamField body="n" type="integer">
  Number of completion choices to generate. Default: `1`.
</ParamField>

## Example Request

```bash theme={null}
curl https://api.boole.dev/v1/chat/completions \
  -H "Authorization: Bearer $BOOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

## Example Response

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "llama-3.3-70b-instruct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 9,
    "total_tokens": 33
  }
}
```

<ResponseField name="id" type="string">
  Unique identifier for the completion. Use this for logging and tracing.
</ResponseField>

<ResponseField name="choices[].message.content" type="string">
  The generated text from the assistant for this choice.
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  Reason generation stopped. Common values: `"stop"` (natural end or stop sequence hit), `"length"` (max\_tokens reached), `"tool_calls"` (model invoked a tool).
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  Number of tokens in the input messages.
</ResponseField>

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

## Streaming

Set `"stream": true` to receive the response as a sequence of server-sent events. Each chunk contains a partial delta, and the stream terminates with `data: [DONE]`.

```bash theme={null}
curl https://api.boole.dev/v1/chat/completions \
  -H "Authorization: Bearer $BOOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count to five."}
    ]
  }'
```

Each server-sent event looks like:

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":"One"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":", two"},"index":0,"finish_reason":null}]}

data: [DONE]
```

Concatenate the `delta.content` values from each chunk to reconstruct the full response.