Chat API

The Chat API lets you send questions and receive AI-generated answers, complete with document citations and verifiable sources.

Conversations

List conversations

GET /api/conversations

Query parameters:

Parameter	Type	Default	Description
page	number	1	Current page
limit	number	20	Results per page
topicId	string	-	Filter by category
search	string	-	Title search

Example:

curl -X GET "https://api.queria.pro/api/conversations?page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "conv_7f2a9b3c",
        "title": "Supply contract analysis",
        "topicId": "topic_456",
        "messageCount": 12,
        "lastMessageAt": "2026-03-04T09:15:00Z",
        "createdAt": "2026-03-03T14:20:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 34, "totalPages": 4 }
  }
}

Create conversation

POST /api/conversations

{
  "title": "New analysis",
  "topicId": "topic_456"
}

Response:

{
  "success": true,
  "data": {
    "id": "conv_e4f5a6b7",
    "title": "New analysis",
    "topicId": "topic_456",
    "messages": []
  }
}

Conversation detail

GET /api/conversations/:id

Returns the conversation with all messages, associated sources and metadata.

Delete conversation

DELETE /api/conversations/:id

Sending messages

Non-streaming message

POST /api/chat/message

Request body:

{
  "message": "What are the penalties in the contract?",
  "conversationId": "conv_7f2a9b3c",
  "topicId": "topic_456",
  "enableExternalSources": true,
  "filters": {
    "documentType": ["pdf", "docx"],
    "dateRange": {
      "from": "2025-01-01",
      "to": "2025-12-31"
    },
    "topics": ["contracts", "legal"],
    "confidentiality": "internal"
  }
}

Field	Type	Required	Description
message	string	Yes	Question text
conversationId	string	No	Existing conversation ID
topicId	string	No	Filter by topic
enableExternalSources	boolean	No	Enable search on external databases
filters	object	No	Contextual search filters

Response:

{
  "success": true,
  "data": {
    "messageId": "msg_c3d4e5f6",
    "response": "Penalties in the contract are regulated by Art. 12 [1]. Specifically, the supplier is subject to a 2% penalty for each day of delay [2], up to a maximum of 15% of total value.",
    "sources": [
      {
        "id": "src_001",
        "documentId": "doc_8f3a2b",
        "documentName": "Supply Contract 2025.pdf",
        "content": "Art. 12 - Penalties. The supplier will be subject to...",
        "score": 0.94,
        "sourceType": "document",
        "page": 8
      },
      {
        "id": "src_002",
        "documentId": "doc_8f3a2b",
        "documentName": "Supply Contract 2025.pdf",
        "content": "12.2 The penalty for late delivery is 2%...",
        "score": 0.89,
        "sourceType": "document",
        "page": 9
      }
    ],
    "citationMap": {
      "1": { "sourceId": "src_001", "documentId": "doc_8f3a2b", "page": 8 },
      "2": { "sourceId": "src_002", "documentId": "doc_8f3a2b", "page": 9 }
    },
    "reasoningMetadata": {
      "strategy": "sequential",
      "steps": [
        { "type": "query_analysis", "duration": 120 },
        { "type": "document_retrieval", "duration": 340, "resultsFound": 7 },
        { "type": "reranking", "duration": 180, "resultsKept": 3 },
        { "type": "generation", "duration": 1200 }
      ],
      "totalDuration": 1840,
      "confidence": 0.91
    },
    "suggestions": [
      "What's the maximum penalty cap?",
      "Are there force majeure clauses?",
      "How is delivery delay calculated?"
    ]
  }
}

Streaming message (SSE)

POST /api/chat/stream

The request body is identical to the non-streaming endpoint. The Accept: text/event-stream header activates streaming.

curl -X POST https://api.queria.pro/api/chat/stream \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"conversationId": "conv_7f2a9b3c", "message": "Summarize the contract"}'

SSE events:

data: {"type":"reasoning","step":"query_analysis","message":"Question analysis..."}

data: {"type":"reasoning","step":"document_retrieval","message":"Searching across 3 collections..."}

data: {"type":"token","content":"Penalties"}

data: {"type":"token","content":" in the contract"}

data: {"type":"token","content":" are regulated by Art. 12 [1]."}

data: {"type":"sources","sources":[{"id":"src_001","documentName":"Supply Contract 2025.pdf","score":0.94,"sourceType":"document"}]}

data: {"type":"done","citationMap":{"1":{"sourceId":"src_001","documentId":"doc_8f3a2b"}},"suggestions":["What's the maximum penalty cap?"]}

JavaScript client:

const response = await fetch('https://api.queria.pro/api/chat/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'qk_live_abc123def456ghi789jkl012',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({
    message: 'What are the contract penalties?',
    conversationId: 'conv_7f2a9b3c'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const event = JSON.parse(line.slice(6));

    switch (event.type) {
      case 'token':
        appendToResponse(event.content);
        break;
      case 'sources':
        displaySources(event.sources);
        break;
      case 'reasoning':
        updateReasoningPanel(event.step, event.message);
        break;
      case 'done':
        finalize(event.citationMap, event.suggestions);
        break;
    }
  }
}

Temporary documents

Upload temporary documents to analyze them in a single chat session. Files are automatically deleted at the end of the conversation.

Upload temporary document

POST /api/chat/upload-temp
Content-Type: multipart/form-data

Field	Type	Description
file	File	Document to analyze
conversationId	string	Destination conversation ID

Response:

{
  "success": true,
  "data": {
    "tempDocId": "tmp_d4e5f6",
    "filename": "report.pdf",
    "status": "PROCESSING"
  }
}

Processing status

GET /api/chat/temp-doc/:id/status

{
  "success": true,
  "data": {
    "id": "tmp_d4e5f6",
    "status": "VECTORIZED",
    "progress": 100,
    "chunksCreated": 24
  }
}

Possible states: PROCESSING, VECTORIZED, ERROR.

Feedback

Let users rate answer quality for continuous improvement.

POST /api/chat/feedback

{
  "messageId": "msg_c3d4e5f6",
  "rating": "positive",
  "comment": "Precise and well-documented answer"
}

The rating field accepts: positive, negative.

Public endpoints (Widget)

Endpoints accessible via API Key, designed for widgets and external integrations.

Method	Endpoint	Description
POST	/api/public/chat/stream	Streaming chat with API Key
POST	/api/public/chat	Non-streaming chat with API Key
GET	/api/public/topics	List of available categories

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the vacation policy?",
    "sessionId": "session_abc123",
    "topicId": "topic_456"
  }'

These endpoints respect the domain restrictions configured for the API key.

Common errors

Code	Error	Description
400	INVALID_CONVERSATION	Conversation not found or access denied
429	RATE_LIMITED	Too many requests, wait before retrying
503	AI_UNAVAILABLE	AI service temporarily unavailable

Best practices

• Use streaming for a better and more reactive UX
• Implement debouncing on inputs to avoid excessive requests
• Handle timeouts (max 60 seconds per response)
• Implement retry with exponential backoff for transient errors
• Display sources for transparency and information verification
• Collect user feedback for continuous improvement