API Overview

Documentazione delle API REST di Queria.

Base URL

Ambiente	URL
Development	https://devadmin.queria.pro/api
Production	https://admin.queria.pro/api

Autenticazione

Due metodi di autenticazione supportati:

JWT Token (Utenti Web)

Authorization: Bearer <jwt-token>

Ottenuto tramite login:

POST /api/auth/login
{
  "email": "user@example.com",
  "password": "password"
}

API Key (Integrazioni)

X-API-Key: qk_live_xxxxxxxxxxxxxxxx

Le API keys sono specifiche per azienda e si generano dalla dashboard.

Formato Risposte

Successo

{
  "success": true,
  "data": { ... }
}

Lista con Paginazione

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

Errore

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [ ... ]
  }
}

Codici di Stato

Codice	Significato
200	OK
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

Rate Limiting

Tipo	Limite
API pubbliche	60 req/min
API autenticate	300 req/min
Upload documenti	10 req/min
Chat streaming	20 req/min

Headers di risposta:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1704067200

Endpoints Principali

Autenticazione

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

Chat

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

Documenti

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

Topics

Metodo	Endpoint	Descrizione
GET	/topics	Lista topics
POST	/topics	Crea topic
PUT	/topics/:id	Aggiorna topic
DELETE	/topics/:id	Elimina topic

Aziende

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

API Pubbliche (Widget)

Endpoint per widget embeddabili (richiedono API Key):

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

Paginazione

Query parameters per liste:

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

Esempio:

GET /api/documents?page=2&limit=50&sort=name&order=asc

Filtri

Query parameters per filtri:

# Documenti per status
GET /api/documents?status=VECTORIZED

# Documenti per topic
GET /api/documents?topicId=uuid

# Ricerca per nome
GET /api/documents?search=contratto

# Combinati
GET /api/documents?status=VECTORIZED&topicId=uuid&search=acme

Webhook (Coming Soon)

Webhook per eventi:

• document.uploaded
• document.vectorized
• document.error
• conversation.created

SDK

SDK ufficiali in sviluppo:

• JavaScript/TypeScript
• Python
• PHP

Nel frattempo, usa le API REST direttamente.