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

# Chat

> Send messages to a ToeBox agent and receive streaming responses

## Send a message

<Note>This endpoint streams responses using Server-Sent Events (SSE). Each chunk is a JSON object sent as a `data:` event.</Note>

### Endpoint

```
POST /api/agents/chat/stream
```

### Headers

| Header          | Value                    | Required |
| --------------- | ------------------------ | -------- |
| `Authorization` | `Bearer tb_your-api-key` | Yes      |
| `Content-Type`  | `application/json`       | Yes      |

### Request body

```json theme={null}
{
  "agent_id": "agent_abc123",
  "message": "What sneakers do you have under $100?",
  "conversation_id": "conv_xyz789",
  "stream": true
}
```

| Field             | Type    | Required | Description                                                                         |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `agent_id`        | string  | Yes      | The ID of the agent to send the message to                                          |
| `message`         | string  | Yes      | The user's message                                                                  |
| `conversation_id` | string  | No       | An existing conversation ID to continue a thread. Omit to start a new conversation. |
| `stream`          | boolean | No       | Whether to stream the response. Default: `true`                                     |

### Response (streaming)

The response is a stream of Server-Sent Events. Each event contains a JSON payload:

```
data: {"type": "text", "content": "Here are some"}
data: {"type": "text", "content": " sneakers under $100:\n\n"}
data: {"type": "tool_use", "tool": "search_products", "input": {"query": "sneakers", "max_price": 100}}
data: {"type": "tool_result", "tool": "search_products", "output": {...}}
data: {"type": "text", "content": "1. **Air Max 90** - $89.99\n2. **Classic Runner** - $74.99"}
data: {"type": "end", "conversation_id": "conv_xyz789"}
```

### Event types

| Type          | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `text`        | A chunk of the agent's text response                                             |
| `tool_use`    | The agent is calling a tool (includes tool name and input)                       |
| `tool_result` | The result from a tool call                                                      |
| `end`         | The response is complete. Includes the `conversation_id` for follow-up messages. |
| `error`       | An error occurred during processing                                              |

### Example: cURL

```bash theme={null}
curl -N -X POST https://your-store.toebox.ai/api/agents/chat/stream \
  -H "Authorization: Bearer tb_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "message": "What sneakers do you have under $100?"
  }'
```

### Example: JavaScript

```javascript theme={null}
const response = await fetch('https://your-store.toebox.ai/api/agents/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tb_your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_abc123',
    message: 'What sneakers do you have under $100?',
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'text') {
      process.stdout.write(data.content);
    }
  }
}
```

### Error responses

| Status | Description                                         |
| ------ | --------------------------------------------------- |
| `400`  | Invalid request body (missing agent\_id or message) |
| `401`  | Invalid or missing API key                          |
| `404`  | Agent not found                                     |
| `429`  | Rate limit exceeded                                 |
| `500`  | Internal server error                               |