Enabling Streaming
To receive a streaming response, set stream: true in the request body of the chat or retry endpoints:
curl -X POST 'https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "Explain quantum computing",
"stream": true,
"conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"userId": "user_abc123"
}'
Request Body
The user message to send to the agent. Omit to continue the conversation after submitting a client action result.
Stream the response as SSE. Defaults to true.
Continue an existing conversation. Omit to create a new one.
Associate a user with a new conversation. Max 128 chars, [a-zA-Z0-9._-] only. Ignored when conversationId is provided.
Once set, a conversation’s userId is immutable — it cannot be changed or removed. See User Conversations for details on managing per-user conversation history.
The response uses Content-Type: text/event-stream and follows the AI SDK UIMessage Stream protocol. Events are newline-delimited JSON, where each line is a JSON object with a type field.
Event Types
Text Events
Client Action Events
Step & Completion Events
message-startEmitted once at the beginning of a new message. Contains the message ID. { "type" : "message-start" , "messageId" : "msg_abc123" }
text-startEmitted at the beginning of a text block. { "type" : "text-start" , "id" : "text_001" }
text-deltaEmitted for each chunk of generated text. Concatenate all deltas to build the full response. { "type" : "text-delta" , "id" : "text_001" , "delta" : "Quantum computing is" }
text-endEmitted when a text block is complete. { "type" : "text-end" , "id" : "text_001" }
These events are emitted when the agent invokes a client action . The toolName corresponds to the name of the configured action. Emitted at the start of a client action input. { "type" : "tool-input-start" , "toolCallId" : "call_abc123" , "toolName" : "lookupOrder" }
Emitted for each chunk of the action input as it streams. { "type" : "tool-input-delta" , "toolCallId" : "call_abc123" , "inputTextDelta" : "{ \" order" }
Emitted when the complete action input is ready. You can read the full input object directly from this event without concatenating the preceding deltas.
{ "type" : "tool-input-available" , "toolCallId" : "call_abc123" , "toolName" : "lookupOrder" , "input" : { "orderId" : "ORD-123" } }
Emitted when a tool execution result is available. The full output can be read directly from this event.
{ "type" : "tool-output-available" , "toolCallId" : "call_abc123" , "output" : { "status" : "shipped" , "eta" : "2026-04-03" } }
For the full client action flow — including how to submit results and continue the conversation — see Client Actions . start-stepEmitted at the start of a processing step. finish-stepEmitted at the end of a processing step. { "type" : "finish-step" }
finishEmitted once when generation is complete. errorEmitted if an error occurs during generation. The stream may have been partially delivered. { "type" : "error" , "errorText" : "An error occurred during generation" }
The finish event is accompanied by a message-metadata event containing Chatbase-specific metadata:
{
"type" : "message-metadata" ,
"messageId" : "msg_abc123" ,
"userMessageId" : "msg_xyz789" ,
"conversationId" : "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" ,
"userId" : "user_abc123" ,
"finishReason" : "stop" ,
"usage" : { "credits" : 2 }
}
Unique ID of the assistant message.
The ID of the user message that triggered this response. For continuation responses, this is the last user message in the conversation.
The conversation ID. Use this for follow-up messages.
The user ID associated with this conversation, or null if none.
Why the model stopped generating:
"stop" — normal completion
"error" — an error occurred
"tool-calls" — the agent invoked a client action — submit the result and continue
Credits consumed by this request.
The stream terminates with data: [DONE].
Code Examples
const response = await fetch (
"https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat" ,
{
method: "POST" ,
headers: {
Authorization: "Bearer YOUR_API_KEY" ,
"Content-Type" : "application/json" ,
},
body: JSON . stringify ({
message: "Explain quantum computing" ,
stream: true ,
// conversationId: "a1b2c3d4-...", // omit to start a new conversation
// userId: "user_abc123", // associate a user with the conversation
}),
}
);
const reader = response . body . getReader ();
const decoder = new TextDecoder ();
let conversationId ;
let userId ;
while ( true ) {
const { done , value } = await reader . read ();
if ( done ) break ;
const lines = decoder . decode ( value , { stream: true }). split ( " \n " );
for ( const line of lines ) {
if ( ! line . trim ()) continue ;
const event = JSON . parse ( line );
switch ( event . type ) {
case "message-start" :
console . log ( "Message ID:" , event . messageId );
break ;
case "text-delta" :
process . stdout . write ( event . delta );
break ;
case "tool-input-available" :
console . log ( " \n Client action requested:" , event . toolName , event . input );
// Handle client action — see Client Actions guide
break ;
case "message-metadata" :
conversationId = event . conversationId ;
userId = event . userId ;
console . log ( " \n Finish reason:" , event . finishReason );
console . log ( "Credits used:" , event . usage . credits );
break ;
case "error" :
console . error ( "Stream error:" , event . errorText );
break ;
}
}
}
Non-Streaming Mode
When stream is set to false, the API returns a standard JSON response with the complete message:
Text Response
Client Action Response
{
"data" : {
"id" : "msg_abc123" ,
"role" : "assistant" ,
"parts" : [
{ "type" : "text" , "text" : "Quantum computing is a type of computation..." }
],
"metadata" : {
"userMessageId" : "msg_xyz789" ,
"conversationId" : "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" ,
"userId" : "user_abc123" ,
"finishReason" : "stop" ,
"usage" : { "credits" : 2 }
}
}
}
When a client action is invoked, the response includes tool-call parts and finishReason: "tool-calls": {
"data" : {
"id" : "msg_abc123" ,
"role" : "assistant" ,
"parts" : [
{ "type" : "text" , "text" : "Let me look up that order for you." },
{ "type" : "tool-call" , "toolCallId" : "call_abc123" , "toolName" : "lookupOrder" , "input" : { "orderId" : "ORD-123" } }
],
"metadata" : {
"userMessageId" : "msg_xyz789" ,
"conversationId" : "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" ,
"userId" : "user_abc123" ,
"finishReason" : "tool-calls" ,
"usage" : { "credits" : 2 }
}
}
}
See Client Actions for how to submit the result and continue the conversation.