Skip to main content
POST
/
api
/
agents
/
{agentId}
/
chat
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "message": "<string>",
  "model": "<string>",
  "tokensUsed": {},
  "ragChunksUsed": 123
}

​
Description

Send a message to an agent and receive a response.

​
Authentication

Required (API key or JWT token)

​
Path Parameters

​
agentId
string
required
The ID of the agent to chat with

​
Request Body

​
message
string
required
The message to send to the agent
​
threadId
string
Optional thread ID for conversation continuity
​
stream
boolean
Whether to stream the response (default: false)
​
attachments
array
Optional file attachments

​
Response

​
message
string
The agent’s response message
​
model
string
The AI model used
​
tokensUsed
object
Token usage statistics (prompt, completion, total)
​
ragChunksUsed
number
Number of knowledge base chunks used

​
Example Request

curl -X POST \
  -H "Authorization: Bearer conv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help?",
    "threadId": "thread_123",
    "stream": false
  }' \
  https://api.convosphere.site/api/agents/agent_123/chat

​
Example Response

{
  "message": "Hello! I'm here to help...",
  "model": "gpt-4",
  "tokensUsed": {
    "prompt": 150,
    "completion": 50,
    "total": 200
  },
  "ragChunksUsed": 3
}

​
Streaming Response

When stream: true, the response is sent as Server-Sent Events (SSE): 
data: {"chunk": "Hello"}
data: {"chunk": "!"}
data: {"chunk": " How"}
data: [DONE]

​
Error Responses

​
400
object
Bad Request - Missing message or invalid parameters
​
401
object
Unauthorized - Invalid or missing authentication
​
403
object
Forbidden - No access to this agent
​
404
object
Not Found - Agent not found