Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Send a message

Send a user message to an agent and receive its reply. 
POST /v1/chat

​
Request body

​
agent_id
string
required
The ID of the agent to chat with. You can find agent IDs using the List agents endpoint.
​
message
string
required
The message to send to the agent.
​
conversation_id
string
The ID of an existing conversation to continue. Omit this field to start a new conversation — the response will include a conversationId you can use in subsequent requests.
When you pass a conversation_id, the agent has memory of the entire prior conversation. Omit it to start fresh with no prior context.
curl -X POST https://your-domain/v1/chat \
  -H "Authorization: Bearer brs_live_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Hello, how can you help me?"
  }'
To continue an existing conversation, include the conversation_id from a prior response: 
curl -X POST https://your-domain/v1/chat \
  -H "Authorization: Bearer brs_live_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Can you elaborate on that last point?",
    "conversation_id": "conv_xxxxxxxxxxxxxxxx"
  }'

​
Response

{
  "response": "I can help you with product questions, billing inquiries, and technical support. What do you need?",
  "conversationId": "conv_xxxxxxxxxxxxxxxx",
  "model": "openai/gpt-4o",
  "usage": {
    "inputTokens": 42,
    "outputTokens": 28,
    "totalTokens": 70,
    "cost": 0.00021
  },
  "sources": [
    {
      "number": 1,
      "kbName": "Product Docs",
      "source": "getting-started.pdf",
      "relevanceScore": 0.91,
      "text": "Our platform supports three core use cases: product Q&A, billing support, and technical troubleshooting."
    }
  ],
  "suggestedFollowUps": [
    "How do I reset my password?",
    "What payment methods do you accept?"
  ]
}
​
response
string
The agent’s reply to your message.
​
conversationId
string
The conversation ID. Pass this as conversation_id in your next request to continue the conversation.
​
model
string
The AI model that generated the response.
​
usage
object
Token usage and cost for this request.
​
usage.inputTokens
number
Number of tokens in the input (prompt + conversation history).
​
usage.outputTokens
number
Number of tokens in the agent’s reply.
​
usage.totalTokens
number
Total tokens consumed.
​
usage.cost
number
Cost of this request in USD.
​
sources
array
Knowledge base chunks that the agent referenced when generating its reply. Present only when the agent has linked knowledge bases and relevant content was found.
​
sources[].number
number
Citation number as referenced in the response.
​
sources[].kbName
string
Name of the knowledge base the chunk came from.
​
sources[].source
string
The source document or URL the chunk originated from.
​
sources[].relevanceScore
number
Relevance score between 0 and 1. Higher values indicate a closer match to the query.
​
sources[].text
string
The text content of the chunk used as context.
​
suggestedFollowUps
array
Optional list of suggested follow-up questions the user might ask next.