Skip to main content
POST
/
agents
/
{agentId}
/
chat
Chat with an agent
curl --request POST \
  --url https://www.chatbase.co/api/v2/agents/{agentId}/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Hello, how can you help me?",
  "conversationId": "<string>",
  "stream": true,
  "userId": "<string>"
}
'
{
  "messageId": "<string>",
  "userMessageId": "<string>",
  "conversationId": "<string>",
  "userId": "<string>",
  "usage": {
    "credits": 2
  }
}

Authorizations

​
Authorization
string
header
required

API key from your account settings

Path Parameters

​
agentId
string
required

The agent ID

Minimum string length: 1
Example:

"5QHA6VB-DIAbBhxwqxfdi"

Body

application/json
​
message
string

The user message to send to the agent. Omit to continue the conversation after submitting a tool result.

Minimum string length: 1
Example:

"Hello, how can you help me?"

​
conversationId
string

Optional conversation ID to continue an existing conversation. If omitted, a new conversation will be started.

​
stream
boolean
default:true

Whether to stream the response as Server-Sent Events (SSE). Defaults to true.

​
userId
string

Optional user ID to associate with a new conversation. Only applied when creating a new conversation (no conversationId). Once set, a conversation's userId is immutable — this field is ignored for existing conversations. Must contain only URL-safe characters (letters, digits, hyphens, underscores, dots).

Maximum string length: 128
Pattern: ^[a-zA-Z0-9._-]+$

Response

Successful response

Streaming response using the AI SDK UIMessage Stream protocol.

Each SSE event has an event: field with the type and a data: field with JSON content.

AI SDK events:

  • message-start — { type, messageId } — Start of a new message
  • text-start — { type, id } — Start of a text block
  • text-delta — { type, id, delta } — Incremental text chunk
  • text-end — { type, id } — End of a text block
  • tool-input-start — { type, toolCallId, toolName } — Start of tool call input
  • tool-input-delta — { type, toolCallId, inputTextDelta } — Incremental tool input
  • tool-input-available — { type, toolCallId, toolName, input } — Complete tool input
  • tool-output-available — { type, toolCallId, output } — Tool execution result
  • start-step — { type } — Start of a processing step
  • finish-step — { type } — End of a processing step
  • finish — { type } — Stream complete
  • error — { type, errorText } — Error occurred

Chatbase metadata (emitted as message-metadata on the finish event): The schema below describes the custom metadata attached to the finish event. Use conversationId for follow-up messages.

Stream terminates with data: [DONE].

​
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

​
usage
object
required

Usage information for this request