Chat API
Query your agent and manage conversations programmatically. This is the core API for getting AI responses from your knowledge base.
Query Agent
/agents/{agentId}/query/Send a message to your agent and receive an AI-generated response based on your knowledge base.
Request Body
messagestringrequiredThe user's question or message (max 10,000 characters)
conversationIduuidContinue an existing conversation. Omit to start new.
dataSourceIdsuuid[]Limit search to specific data sources. Omit to search all.
Example Request
Response
{
"response": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. To initiate a return, visit your order history and click 'Return Item'. Refunds are processed within 5-7 business days.",
"conversationId": "conv_abc123",
"messageId": "msg_xyz789",
"sources": [
{
"rank": 1,
"documentId": "doc_123",
"chunkId": "chunk_456",
"title": "Return Policy - Help Center",
"dataSourceName": "Help Center",
"dataSourceType": "web",
"sourceUrl": "https://help.example.com/returns",
"content": "...returns within 30 days of purchase. Items must be unused...",
"score": 0.94,
"displayMode": "expandable"
},
{
"rank": 2,
"documentId": "doc_456",
"chunkId": "chunk_789",
"title": "Refund Processing",
"dataSourceName": "Help Center",
"dataSourceType": "web",
"sourceUrl": "https://help.example.com/refunds",
"content": "...refunds are processed within 5-7 business days...",
"score": 0.87,
"displayMode": "expandable"
}
],
"latency": 823,
"model": "gpt-4o",
"retrievedChunks": 5,
"metadata": {
"tokensUsed": 450,
"retrievalTime": 120,
"generationTime": 703
}
}Response Fields
QueryResponse
responsestringGenerated answer from the AI
conversationIduuidConversation ID for follow-ups
messageIduuidUnique message identifier
sourcesSource[]Source citations used for the answer
latencyintegerTotal response time in milliseconds
modelstringAI model used
retrievedChunksintegerNumber of chunks retrieved
metadataobjectAdditional timing and usage info
Source Object
Source
rankintegerRelevance ranking (1 = most relevant)
documentIdstringSource document ID
titlestringDocument or section title
dataSourceNamestringName of the data source
dataSourceTypestringType: pdf, web, notion, etc.
sourceUrlstringURL if available
contentstringSnippet of matched content
scorenumberRelevance score (0-1)
Continuing Conversations
To maintain context across multiple messages, include the conversationId from the previous response:
-green-500">"text-muted-foreground"># First message
-purple-500">curl -X POST https://api.ragchats.ai/api/agents/AGENT_ID/query/ \
-H -green-500">"Authorization: Bearer YOUR_API_KEY" \
-d -green-500">'{"message-green-500">": "What is your return policy?-green-500">"}'
-green-500">"text-muted-foreground"># Returns: {-green-500">"conversationId": -green-500">"conv_abc123", ...}
-green-500">"text-muted-foreground"># Follow-up message (with context)
-purple-500">curl -X POST https://api.ragchats.ai/api/agents/AGENT_ID/query/ \
-H -green-500">"Authorization: Bearer YOUR_API_KEY" \
-d '{
-green-500">"message": -green-500">"What about for electronics?",
-green-500">"conversationId": -green-500">"conv_abc123"
}'Conversation Memory
The agent remembers the last 10 messages in a conversation. For longer conversations, older context may be summarized or dropped.
List Conversations
/agents/{agentId}/conversations/List all conversations for an agent.
Query Parameters
pageintegerdefault: 1Page number
page_sizeintegerdefault: 20Results per page (max 100)
Response
{
"count": 150,
"next": "https://api.ragchats.ai/api/agents/AGENT_ID/conversations/?page=2",
"previous": null,
"results": [
{
"id": "conv_abc123",
"title": "Return policy questions",
"messageCount": 5,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:45:00Z"
}
]
}Streaming Responses
For real-time streaming responses, use Server-Sent Events (SSE):
500">const response = 500">await fetch(
500">class="text-green-500">"https:500">class="text-muted-foreground500">class="text-green-500">">//api.ragchats.ai/api/agents/AGENT_ID/query/",
{
method: 500">class="text-green-500">"POST",
headers: {
500">class="text-green-500">"Authorization": 500">class="text-green-500">"Bearer YOUR_API_KEY",
500">class="text-green-500">"Content-Type": 500">class="text-green-500">"application/json",
500">class="text-green-500">"Accept": 500">class="text-green-500">"text/event-stream"
},
body: JSON.stringify({
message: 500">class="text-green-500">"Explain your pricing tiers"
})
}
);
500">const reader = response.body.getReader();
500">const decoder = 500">new TextDecoder();
500">while (500">true) {
500">const { done, value } = 500">await reader.read();
500">if (done) break;
500">const chunk = decoder.decode(value);
500">const lines = chunk.split(500">class="text-green-500">"\n");
500">for (500">const line of lines) {
500">if (line.startsWith(500">class="text-green-500">"data: ")) {
500">const data = JSON.parse(line.slice(6));
500">if (data.type === 500">class="text-green-500">"token") {
process.stdout.write(data.token);
} 500">else 500">if (data.type === 500">class="text-green-500">"sources") {
console.log(500">class="text-green-500">"\nSources:", data.sources);
} 500">else 500">if (data.type === 500">class="text-green-500">"done") {
console.log(500">class="text-green-500">"\nComplete!");
}
}
}
}Stream Events
starteventStream started. Contains query_id.
tokeneventSingle token of response text.
sourceseventSource citations (sent after text).
doneeventStream complete. Contains final metadata.
erroreventError occurred during generation.
Error Handling
Common errors for the query endpoint:
400Bad RequestInvalid message or parameters
401UnauthorizedInvalid or missing API key
404Not FoundAgent not found or not accessible
429Rate LimitedToo many requests. Retry after delay.
503UnavailableAgent is still processing data sources. Try later.

