Chat API

The Chat API provides an interactive conversational interface for data analysis. Users can ask questions in natural language, and Querri generates and executes data queries, returning results in a streaming format.

Base URL

https://api.querri.com/api

Authentication

All Chat API endpoints require JWT authentication. See Authentication for details.

Endpoints

Send Chat Message

Send a message to the chat interface for a specific project. The API responds with streaming Server-Sent Events (SSE) containing steps, execution updates, and results.

POST /api/projects/{uuid}/chat

Headers:

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
Accept: text/event-stream

Path Parameters:

Parameter	Type	Description
uuid	string	Project UUID to provide context for the chat

Request Body:

{
  "message": "Show me the top 10 customers by revenue in Q4",
  "model": "gpt-4o",
  "context": {
    "previous_message_id": "msg_01ABCDEF",
    "include_history": true
  },
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  }
}

Request Parameters:

Field	Type	Required	Description
message	string	Yes	User’s natural language query
model	string	No	LLM model to use (default: gpt-4o)
context.previous_message_id	string	No	ID of previous message for conversation continuity
context.include_history	boolean	No	Include full conversation history (default: true)
parameters.temperature	float	No	LLM temperature 0.0-2.0 (default: 0.7)
parameters.max_tokens	integer	No	Maximum response tokens (default: 2000)

---

Streaming Responses

The Chat API uses Server-Sent Events (SSE) to stream responses in real-time. Each event contains a JSON payload with the current state.

Event Types

1. Message Acknowledgment

First event confirming message received:

event: message_received
data: {"message_id": "msg_01ABCDEF", "timestamp": "2025-01-15T10:00:00Z"}

2. Thinking/Analysis

AI is analyzing the request:

event: thinking
data: {"status": "analyzing", "message": "Analyzing your request..."}

3. Step Created

A new execution step was created:

event: step_created
data: {
  "step_id": "step_01ABCDEF",
  "type": "sql_query",
  "name": "Extract top customers by revenue",
  "order": 1
}

4. Step Executing

Step execution started:

event: step_executing
data: {
  "step_id": "step_01ABCDEF",
  "status": "running",
  "started_at": "2025-01-15T10:00:05Z"
}

5. Step Progress

Progress updates during execution:

event: step_progress
data: {
  "step_id": "step_01ABCDEF",
  "progress": {
    "percentage": 45,
    "rows_processed": 4500,
    "estimated_total": 10000
  }
}

6. Step Completed

Step finished successfully:

event: step_completed
data: {
  "step_id": "step_01ABCDEF",
  "status": "completed",
  "completed_at": "2025-01-15T10:00:15Z",
  "duration_seconds": 10,
  "result_summary": {
    "rows": 10,
    "columns": 3,
    "data_url": "/api/projects/proj_01ABCDEF/steps/step_01ABCDEF/data"
  }
}

7. Step Failed

Step execution failed:

event: step_failed
data: {
  "step_id": "step_01ABCDEF",
  "status": "failed",
  "error": {
    "code": "sql_execution_error",
    "message": "Table 'customers' does not exist",
    "details": "Check your database schema"
  }
}

8. Response Token

LLM generating response text (streamed token by token):

event: response_token
data: {"token": "Based", "position": 0}

event: response_token
data: {"token": " on", "position": 1}

event: response_token
data: {"token": " the", "position": 2}

9. Response Complete

Full response finished:

event: response_complete
data: {
  "message_id": "msg_01GHIJKL",
  "response": "Based on the data, here are the top 10 customers by revenue in Q4:\n\n1. Acme Corp - $125,000\n2. TechStart Inc - $98,500\n...",
  "steps": ["step_01ABCDEF"],
  "execution_time_seconds": 12
}

10. Error

Error during processing:

event: error
data: {
  "error": "execution_failed",
  "message": "Failed to execute query",
  "step_id": "step_01ABCDEF",
  "recoverable": true
}

11. Done

Stream complete:

event: done
data: {"timestamp": "2025-01-15T10:00:20Z"}

---

Complete Example

Request

curl -N -X POST "https://api.querri.com/api/projects/proj_01ABCDEF/chat" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Show me the top 10 customers by revenue in Q4",
    "model": "gpt-4o",
    "context": {
      "include_history": true
    }
  }'

Response Stream

event: message_received
data: {"message_id": "msg_01ABCDEF", "timestamp": "2025-01-15T10:00:00Z"}

event: thinking
data: {"status": "analyzing", "message": "Analyzing your request..."}

event: step_created
data: {"step_id": "step_01ABCDEF", "type": "sql_query", "name": "Extract top customers", "order": 1}

event: step_executing
data: {"step_id": "step_01ABCDEF", "status": "running", "started_at": "2025-01-15T10:00:05Z"}

event: step_progress
data: {"step_id": "step_01ABCDEF", "progress": {"percentage": 50, "rows_processed": 5000}}

event: step_completed
data: {
  "step_id": "step_01ABCDEF",
  "status": "completed",
  "completed_at": "2025-01-15T10:00:15Z",
  "duration_seconds": 10,
  "result_summary": {
    "rows": 10,
    "columns": 3,
    "data_url": "/api/projects/proj_01ABCDEF/steps/step_01ABCDEF/data"
  }
}

event: response_token
data: {"token": "Based on the Q4 data, here are the top 10 customers:\n\n"}

event: response_token
data: {"token": "1. **Acme Corp** - $125,000\n"}

event: response_token
data: {"token": "2. **TechStart Inc** - $98,500\n"}

event: response_complete
data: {
  "message_id": "msg_01GHIJKL",
  "response": "Based on the Q4 data, here are the top 10 customers:\n\n1. **Acme Corp** - $125,000\n2. **TechStart Inc** - $98,500\n...",
  "steps": ["step_01ABCDEF"],
  "execution_time_seconds": 12
}

event: done
data: {"timestamp": "2025-01-15T10:00:20Z"}

---

Response Format

Data Structure

Each SSE event follows this structure:

event: {event_type}
data: {json_payload}

Events are separated by blank lines. The data field always contains valid JSON.

---

Context Handling

The Chat API maintains conversation context across multiple messages.

Continuing a Conversation

# First message
curl -X POST "https://api.querri.com/api/projects/proj_01ABCDEF/chat" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me total revenue by month"}'

# Follow-up message (using previous message_id)
curl -X POST "https://api.querri.com/api/projects/proj_01ABCDEF/chat" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Now break that down by product category",
    "context": {
      "previous_message_id": "msg_01ABCDEF",
      "include_history": true
    }
  }'

Context Window

• Chat history is automatically managed
• Last 10 messages are included by default
• Context includes previous queries, results, and generated steps
• Long contexts are automatically summarized

---

Model Selection

Available Models

Model	Description	Best For
gpt-4o	GPT-4 Omni (default)	Complex analysis, multi-step queries
gpt-4-turbo	Fast GPT-4	Quick queries, simple aggregations
claude-3-5-sonnet	Claude Sonnet	Code generation, detailed explanations
claude-3-5-haiku	Claude Haiku	Simple queries, fast responses

Model-Specific Parameters

{
  "message": "Analyze sales trends",
  "model": "gpt-4o",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2000,
    "top_p": 0.9,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  }
}

---

Error Handling

Common Errors

Invalid Project

{
  "error": "not_found",
  "message": "Project not found or access denied",
  "project_uuid": "proj_01INVALID"
}

HTTP Status: 404 Not Found

Invalid Message

{
  "error": "validation_error",
  "message": "Message is required and cannot be empty",
  "field": "message"
}

HTTP Status: 400 Bad Request

Connector Not Available

event: error
data: {
  "error": "connector_unavailable",
  "message": "Database connector is not accessible",
  "connector_uuid": "conn_01ABCDEF",
  "recoverable": false
}

Query Execution Failed

event: step_failed
data: {
  "step_id": "step_01ABCDEF",
  "error": {
    "code": "sql_execution_error",
    "message": "Syntax error in SQL query",
    "query": "SELECT * FORM customers",
    "details": "Did you mean 'FROM' instead of 'FORM'?"
  }
}

---

Client Implementation Examples

JavaScript (Browser)

const eventSource = new EventSource(
  'https://api.querri.com/api/projects/proj_01ABCDEF/chat',
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    method: 'POST',
    body: JSON.stringify({
      message: 'Show me top customers',
      model: 'gpt-4o'
    })
  }
);

eventSource.addEventListener('step_created', (e) => {
  const data = JSON.parse(e.data);
  console.log('Step created:', data.step_id);
});

eventSource.addEventListener('response_token', (e) => {
  const data = JSON.parse(e.data);
  document.getElementById('response').innerHTML += data.token;
});

eventSource.addEventListener('done', (e) => {
  console.log('Stream complete');
  eventSource.close();
});

eventSource.addEventListener('error', (e) => {
  console.error('Stream error:', e);
  eventSource.close();
});

Python

import requests
import json

url = "https://api.querri.com/api/projects/proj_01ABCDEF/chat"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
}
payload = {
    "message": "Show me top customers",
    "model": "gpt-4o"
}

response = requests.post(url, headers=headers, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('event:'):
            event_type = line.split(':', 1)[1].strip()
        elif line.startswith('data:'):
            data = json.loads(line.split(':', 1)[1].strip())
            print(f"{event_type}: {data}")

cURL (with line-by-line output)

curl -N -X POST "https://api.querri.com/api/projects/proj_01ABCDEF/chat" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Show me top customers",
    "model": "gpt-4o"
  }'

---

Rate Limiting

Chat API has specific rate limits:

Limit Type	Value	Window
Messages per user	100	1 hour
Concurrent streams	3	Per user
Token generation rate	10,000	Per minute

When rate limited:

event: error
data: {
  "error": "rate_limit_exceeded",
  "message": "Too many concurrent chat streams",
  "retry_after": 60
}

HTTP Status: 429 Too Many Requests

---

Best Practices

1. Handle Reconnection - Implement exponential backoff for connection failures
2. Process Events Incrementally - Update UI as events arrive, don’t wait for completion
3. Store Message IDs - Track conversation history using message IDs
4. Handle Errors Gracefully - Display user-friendly error messages
5. Implement Timeouts - Close connections after reasonable timeout (e.g., 5 minutes)
6. Buffer Response Tokens - Batch token updates to avoid excessive DOM updates
7. Cancel Long-Running Queries - Provide user option to cancel execution

---

Conversation Flow Example

User: "Show me revenue by month"
  → step_created: SQL query to aggregate revenue
  → step_executing: Running query
  → step_completed: 12 rows returned
  → response: "Here's the monthly revenue..." [with data]

User: "Now show only Q4"
  → [Using context from previous message]
  → step_created: SQL query with WHERE clause for Q4
  → step_executing: Running filtered query
  → step_completed: 3 rows returned
  → response: "Q4 revenue breakdown..." [with filtered data]

User: "Create a chart"
  → step_created: Visualization step
  → step_executing: Generating chart
  → step_completed: Chart generated
  → response: "Here's the chart..." [with image URL]

---

HTTP Status Codes

Code	Description
200	Success - stream started
400	Bad Request - invalid message or parameters
401	Unauthorized - missing/invalid token
403	Forbidden - no access to project
404	Not Found - project doesn’t exist
429	Too Many Requests - rate limited
500	Internal Server Error