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

FieldTypeRequiredDescription
messagestringYesThe user message to send to the agent.
streambooleanNoStream the response as SSE. Defaults to true.
conversationIdstringNoContinue an existing conversation. Omit to create a new one.
userIdstringNoAssociate 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 v5 UI Message Stream protocol, indicated by the x-vercel-ai-ui-message-stream: v1 header.

​
Event Types

The stream emits newline-delimited JSON events. Each event has a type field:

​
start

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

​
text-delta

Emitted for each chunk of generated text. Concatenate all deltas to build the full response. 
{ "type": "text-delta", "delta": "Quantum computing is" }

{ "type": "text-delta", "delta": " a type of computation" }

​
finish

Emitted once when generation is complete. Contains metadata including the conversation ID, user ID, and credit usage. 
{
  "type": "finish",
  "finishReason": "stop",
  "metadata": {
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "userId": "user_abc123",
    "usage": { "credits": 2 }
  }
}

​
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 "start":
        console.log("Message ID:", event.messageId);
        break;
      case "text-delta":
        process.stdout.write(event.delta);
        break;
      case "finish":
        conversationId = event.metadata.conversationId;
        userId = event.metadata.userId;
        console.log("\nCredits used:", event.metadata.usage.credits);
        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 }
    }
  }
}