K Suite Analytics API

Documentazione frontend-oriented per Lovable. Il backend espone un motore di report dinamico su ClickHouse: il frontend lavora con metadati e payload JSON, non con SQL raw.

OpenAPI first ClickHouse read-only Report builder Dashboard ready

Flusso Consigliato

  • Chiama /tables e /metrics al bootstrap.
  • Quando l'utente sceglie una tabella, chiama /schema.
  • Carica domini reali da /domains.
  • Per filtri guidati usa /field-values.
  • Usa /report/preview per debug o explain UI.
  • Usa /report per ottenere i dati da mostrare in grafici e tabelle.

Regole Chiave

  • Il filtro domain IN (...) è sempre obbligatorio.
  • Serve sempre almeno un filtro data.
  • Se selezioni dimensioni, il backend aggiunge GROUP BY automatico.
  • Le metriche sono whitelistate: events, sessions, revenue.
  • properties_v3 è disponibile ma va evitata come default.

Endpoint Principali

Endpoint Scopo Uso nel frontend
POST /report Esegue il report aggregato. Grafici, KPI, tabelle, drill-down.
POST /report/preview Mostra SQL e parametri bindati. Debug, explain, tool dev.
GET /schema Restituisce campi, tipi e metriche supportate. Configurazione del report builder.
GET /domains Suggerisce domini reali dal DB. Selettore dominio.
GET /field-values Suggerisce valori reali per i filtri. Autocomplete filtri.

Mapping Grafici

  • 0 dimensioni: KPI aggregato.
  • 1 dimensione: bar chart o line chart.
  • 2 dimensioni: stacked bar, grouped bar, drill-down table.
  • Dimensione temporale come month o date: trend chart.

URL Utili

  • /q/openapi?format=json
  • /q/openapi?format=yaml
  • /q/swagger-ui/
  • /dev/