Chat API

La Chat API consente di inviare domande e ricevere risposte generate dall'intelligenza artificiale, complete di citazioni documentali e fonti verificabili.

Conversazioni

Elenco conversazioni

GET /api/conversations

Query parameters:

Parametro	Tipo	Default	Descrizione
page	number	1	Pagina corrente
limit	number	20	Risultati per pagina
topicId	string	-	Filtra per categoria
search	string	-	Ricerca nel titolo

Esempio:

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

Risposta:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "conv_7f2a9b3c",
        "title": "Analisi contratto fornitura",
        "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 }
  }
}

Crea conversazione

POST /api/conversations

{
  "title": "Nuova analisi",
  "topicId": "topic_456"
}

Risposta:

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

Dettaglio conversazione

GET /api/conversations/:id

Restituisce la conversazione con tutti i messaggi, le fonti associate e i metadati.

Elimina conversazione

DELETE /api/conversations/:id

Invio Messaggi

Messaggio non-streaming

POST /api/chat/message

Request body:

{
  "message": "Quali sono le penali previste nel contratto?",
  "conversationId": "conv_7f2a9b3c",
  "topicId": "topic_456",
  "enableExternalSources": true,
  "filters": {
    "documentType": ["pdf", "docx"],
    "dateRange": {
      "from": "2025-01-01",
      "to": "2025-12-31"
    },
    "topics": ["contratti", "legale"],
    "confidentiality": "internal"
  }
}

Campo	Tipo	Obbligatorio	Descrizione
message	string	Si	Testo della domanda
conversationId	string	No	ID conversazione esistente
topicId	string	No	Filtra per categoria tematica
enableExternalSources	boolean	No	Abilita ricerca su banche dati esterne
filters	object	No	Filtri contestuali per la ricerca

Risposta:

{
  "success": true,
  "data": {
    "messageId": "msg_c3d4e5f6",
    "response": "Le penali previste nel contratto sono disciplinate dall'Art. 12 [1]. In particolare, il fornitore e soggetto a una penale del 2% per ogni giorno di ritardo [2], fino a un massimo del 15% del valore totale.",
    "sources": [
      {
        "id": "src_001",
        "documentId": "doc_8f3a2b",
        "documentName": "Contratto Fornitura 2025.pdf",
        "content": "Art. 12 - Penali. Il fornitore sara soggetto...",
        "score": 0.94,
        "sourceType": "document",
        "page": 8
      },
      {
        "id": "src_002",
        "documentId": "doc_8f3a2b",
        "documentName": "Contratto Fornitura 2025.pdf",
        "content": "12.2 La penale per ritardata consegna e pari al 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": [
      "Qual e il tetto massimo delle penali?",
      "Esistono clausole di forza maggiore?",
      "Come si calcola il ritardo nella consegna?"
    ]
  }
}

Messaggio streaming (SSE)

POST /api/chat/stream

Il body della richiesta e identico all'endpoint non-streaming. L'header Accept: text/event-stream attiva lo 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": "Riassumi il contratto"}'

Eventi SSE:

data: {"type":"reasoning","step":"query_analysis","message":"Analisi della domanda..."}

data: {"type":"reasoning","step":"document_retrieval","message":"Ricerca in 3 collezioni..."}

data: {"type":"token","content":"Le penali"}

data: {"type":"token","content":" previste nel contratto"}

data: {"type":"token","content":" sono disciplinate dall'Art. 12 [1]."}

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

data: {"type":"done","citationMap":{"1":{"sourceId":"src_001","documentId":"doc_8f3a2b"}},"suggestions":["Qual e il tetto massimo delle penali?"]}

Client JavaScript:

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: 'Quali sono le penali del contratto?',
    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;
    }
  }
}

Documenti Temporanei

Carica documenti temporanei per analizzarli in una singola sessione di chat. I file vengono eliminati automaticamente al termine della conversazione.

Upload documento temporaneo

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

Campo	Tipo	Descrizione
file	File	Documento da analizzare
conversationId	string	ID conversazione di destinazione

Risposta:

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

Stato elaborazione

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

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

Gli stati possibili sono: PROCESSING, VECTORIZED, ERROR.

Feedback

Consenti agli utenti di valutare la qualita delle risposte per miglioramento continuo.

POST /api/chat/feedback

{
  "messageId": "msg_c3d4e5f6",
  "rating": "positive",
  "comment": "Risposta precisa e ben documentata"
}

Il campo rating accetta: positive, negative.

Endpoint Pubblici (Widget)

Endpoint accessibili tramite API Key, progettati per widget e integrazioni esterne.

Metodo	Endpoint	Descrizione
POST	/api/public/chat/stream	Chat streaming con API Key
POST	/api/public/chat	Chat non-streaming con API Key
GET	/api/public/topics	Lista categorie disponibili

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Qual e la policy sulle ferie?",
    "sessionId": "session_abc123",
    "topicId": "topic_456"
  }'

Questi endpoint rispettano le restrizioni di dominio configurate per la chiave API.

Errori Comuni

Codice	Errore	Descrizione
400	INVALID_CONVERSATION	Conversazione non trovata o accesso negato
429	RATE_LIMITED	Troppe richieste, attendere prima di riprovare
503	AI_UNAVAILABLE	Servizio AI temporaneamente non disponibile

Best Practice

• Utilizza lo streaming per un'esperienza utente migliore e piu reattiva
• Implementa il debouncing sugli input per evitare richieste eccessive
• Gestisci i timeout (massimo 60 secondi per risposta)
• Implementa il retry con backoff esponenziale per errori transitori
• Visualizza le fonti per trasparenza e verifica delle informazioni
• Raccogli il feedback degli utenti per il miglioramento continuo