Chat API

Query your agent and manage conversations programmatically. This is the core API for getting AI responses from your knowledge base.

Query Agent

POST/agents/{agentId}/query/

Send a message to your agent and receive an AI-generated response based on your knowledge base.

Request Body

messagestringrequired

The user's question or message (max 10,000 characters)

conversationIduuid

Continue 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

responsestring

Generated answer from the AI

conversationIduuid

Conversation ID for follow-ups

messageIduuid

Unique message identifier

sourcesSource[]

Source citations used for the answer

latencyinteger

Total response time in milliseconds

modelstring

AI model used

retrievedChunksinteger

Number of chunks retrieved

metadataobject

Additional timing and usage info

Source Object

Source

rankinteger

Relevance ranking (1 = most relevant)

documentIdstring

Source document ID

titlestring

Document or section title

dataSourceNamestring

Name of the data source

dataSourceTypestring

Type: pdf, web, notion, etc.

sourceUrlstring

URL if available

contentstring

Snippet of matched content

scorenumber

Relevance 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

GET/agents/{agentId}/conversations/

List all conversations for an agent.

Query Parameters

pageintegerdefault: 1

Page number

page_sizeintegerdefault: 20

Results 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

startevent

Stream started. Contains query_id.

tokenevent

Single token of response text.

sourcesevent

Source citations (sent after text).

doneevent

Stream complete. Contains final metadata.

errorevent

Error occurred during generation.

Error Handling

Common errors for the query endpoint:

400Bad Request

Invalid message or parameters

401Unauthorized

Invalid or missing API key

404Not Found

Agent not found or not accessible

429Rate Limited

Too many requests. Retry after delay.

503Unavailable

Agent is still processing data sources. Try later.