Send a message
This endpoint streams responses using Server-Sent Events (SSE). Each chunk is a JSON object sent as a
data: event.Endpoint
POST /api/agents/chat/stream
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer tb_your-api-key | Yes |
Content-Type | application/json | Yes |
Request body
{
"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
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
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 |