Panoramica API

La REST API di Queria consente di integrare le funzionalita di ricerca documentale intelligente, chat AI e gestione documenti all'interno di qualsiasi applicazione.

Base URL

Tutte le richieste API utilizzano il seguente base URL:

https://api.queria.pro

L'API segue il versionamento tramite path. La versione corrente e v3.1.0. Gli endpoint pubblici sono accessibili sotto /api/public/, mentre quelli autenticati sotto /api/.

Formato delle Risposte

Tutte le risposte sono in formato JSON con una struttura consistente.

Risposta di successo:

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "Contratto Fornitura 2025",
    "status": "VECTORIZED",
    "createdAt": "2026-02-15T10:30:00Z"
  }
}

Risposta con paginazione:

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Risposta di errore:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Il campo 'message' e obbligatorio.",
    "details": [
      { "field": "message", "reason": "Campo richiesto" }
    ]
  }
}

Codici di Stato HTTP

Codice	Significato	Descrizione
200	OK	Richiesta completata con successo
201	Created	Risorsa creata con successo
400	Bad Request	Parametri mancanti o non validi
401	Unauthorized	Autenticazione mancante o non valida
403	Forbidden	Permessi insufficienti per l'operazione
404	Not Found	Risorsa non trovata
429	Too Many Requests	Limite di richieste superato
500	Internal Server Error	Errore interno del server

Rate Limiting

L'API applica limiti di frequenza per garantire stabilita e prestazioni.

Tipo di Endpoint	Limite	Finestra
Endpoint pubblici	60 richieste	1 minuto
Endpoint autenticati	300 richieste	1 minuto
Upload documenti	10 richieste	1 minuto
Chat streaming	20 richieste	1 minuto

Le risposte includono header informativi sul rate limit:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709542800

Quando il limite viene superato, l'API restituisce un errore 429:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite di richieste superato. Riprova tra 23 secondi.",
    "retryAfter": 23
  }
}

Content-Type

Tutte le richieste JSON devono includere l'header:

Content-Type: application/json

Per gli upload di file, utilizzare:

Content-Type: multipart/form-data

Autenticazione

L'API supporta due metodi di autenticazione:

• JWT Token: per sessioni utente nelle applicazioni web. Incluso tramite header Authorization: Bearer {token}.
• API Key: per integrazioni server-to-server e widget. Inclusa tramite header X-API-Key.

Le API Key seguono il formato qk_live_* per la produzione e qk_test_* per gli ambienti di test.

Per i dettagli completi, consulta la guida all'autenticazione.

Esempio Rapido

Una chiamata tipica alla chat API con autenticazione tramite API Key:

curl -X POST https://api.queria.pro/api/public/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qk_live_abc123def456ghi789" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Quali sono le clausole principali del contratto?",
    "sessionId": "sess_a1b2c3d4"
  }'

Risposta streaming (Server-Sent Events):

data: {"type":"token","content":"Le clausole"}
data: {"type":"token","content":" principali del contratto"}
data: {"type":"token","content":" sono le seguenti [1]:"}
data: {"type":"sources","sources":[{"id":"doc_8f3a","name":"Contratto Fornitura","score":0.92}]}
data: {"type":"done","citationMap":{"1":{"documentId":"doc_8f3a","chunkId":"chk_001"}}}

Endpoint Principali

Autenticazione

Metodo	Endpoint	Descrizione
POST	/api/auth/login	Login utente
POST	/api/auth/register	Registrazione
POST	/api/auth/refresh	Refresh token
POST	/api/auth/logout	Logout

Chat

Metodo	Endpoint	Descrizione
GET	/api/conversations	Lista conversazioni
POST	/api/conversations	Nuova conversazione
POST	/api/chat/message	Invia messaggio
POST	/api/chat/stream	Chat streaming

Documenti

Metodo	Endpoint	Descrizione
GET	/api/documents	Lista documenti
POST	/api/documents/upload	Upload documento
GET	/api/documents/:id	Dettaglio documento
PUT	/api/documents/:id	Aggiorna documento
DELETE	/api/documents/:id	Elimina documento

Topics

Metodo	Endpoint	Descrizione
GET	/api/topics	Lista categorie
POST	/api/topics	Crea categoria
PUT	/api/topics/:id	Aggiorna categoria
DELETE	/api/topics/:id	Elimina categoria

Aziende

Metodo	Endpoint	Descrizione
GET	/api/companies	Lista aziende
GET	/api/companies/:id	Dettaglio azienda
PUT	/api/companies/:id	Aggiorna azienda

API Pubbliche (Widget)

Metodo	Endpoint	Descrizione
POST	/api/public/chat	Chat non-streaming
POST	/api/public/chat/stream	Chat streaming SSE
POST	/api/public/search/web	Ricerca web
GET	/api/public/topics	Lista categorie

Paginazione

Query parameters standard per le liste:

Parametro	Default	Descrizione
page	1	Numero pagina
limit	20	Elementi per pagina (max 100)
sort	createdAt	Campo ordinamento
order	desc	Direzione: asc o desc

Esempio:

curl -X GET "https://api.queria.pro/api/documents?page=2&limit=50&sort=name&order=asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Webhook (Coming Soon)

Notifiche per eventi asincroni:

• document.uploaded - Documento caricato
• document.vectorized - Elaborazione completata
• document.error - Errore di elaborazione
• conversation.created - Nuova conversazione

SDK

SDK ufficiali in fase di sviluppo:

• JavaScript / TypeScript
• Python
• PHP

Nel frattempo, utilizza la REST API direttamente con qualsiasi client HTTP.

Prossimi Passi

• Autenticazione - Configurare JWT e API Key
• Chat API - Inviare messaggi e ricevere risposte AI
• Documenti API - Caricare e gestire documenti
• Integrazioni - Incorporare Queria nella tua applicazione