Skip to main content

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

message
string
The user message to send to the agent. Omit to continue the conversation after submitting a client action result.
stream
boolean
default:true
Stream the response as SSE. Defaults to true.
conversationId
string
Continue an existing conversation. Omit to create a new one.
userId
string
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

message-start

Emitted once at the beginning of a new message. Contains the message ID.
{ "type": "message-start", "messageId": "msg_abc123" }

text-start

Emitted at the beginning of a text block.
{ "type": "text-start", "id": "text_001" }

text-delta

Emitted 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-end

Emitted when a text block is complete.
{ "type": "text-end", "id": "text_001" }

Metadata

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 }
}
messageId
string
required
Unique ID of the assistant message.
userMessageId
string
required
The ID of the user message that triggered this response. For continuation responses, this is the last user message in the conversation.
conversationId
string
required
The conversation ID. Use this for follow-up messages.
userId
string | null
required
The user ID associated with this conversation, or null if none.
finishReason
string
required
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
usage
object
required
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("\nClient 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("\nFinish 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:
{
  "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 }
    }
  }
}