Documentazione API

Autenticazione

Tutte le richieste API richiedono un token Bearer nell' Authorization intestazione. Generare le chiavi API da Impostazioni.

curl -H "Authorization: Bearer sg_live_your_key_here" \
     https://siteguardian.io/api/v1/monitors

Limite di frequenza: 120 richieste al minuto per chiave API. Il superamento restituisce 429 Too Many Requests.

Formato della risposta

Tutte le risposte restituiscono JSON con una struttura coerente:

// Success
{
  "data": { ... },
  "meta": { "timestamp": "2026-03-20T14:30:00+00:00" }
}

// Paginated
{
  "data": [ ... ],
  "meta": { "total": 42, "limit": 50, "offset": 0 }
}

// Error
{
  "detail": "Monitor not found."
}

Endpoint

M Monitor

Metodo	Endpoint	Descrizione
GET	/api/v1/monitors	Elenco di tutti i monitor
POST	/api/v1/monitors	Crea un monitor
GET	/api/v1/monitors/:id	Dettagli del monitor
PATCH	/api/v1/monitors/:id	Aggiorna impostazioni del monitor
DELETE	/api/v1/monitors/:id	Elimina monitor
POST	/api/v1/monitors/:id/pause	Sospendi monitoraggio
POST	/api/v1/monitors/:id/resume	Riprendi monitoraggio

Esempio: Crea un monitor

curl -X POST https://siteguardian.io/api/v1/monitors \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "name": "My Website",
    "check_type": "all"
  }'

Esempio: Aggiorna impostazioni del monitor

curl -X PATCH https://siteguardian.io/api/v1/monitors/:id \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "ssl_warn_days": 14,
    "rt_alert_enabled": true,
    "rt_sensitivity": 2.5
  }'

C Risultati dei controlli

Metodo	Endpoint	Descrizione
GET	/api/v1/monitors/:id/checks	Elenco risultati dei controlli (paginato)
GET	/api/v1/monitors/:id/uptime	Ottieni percentuale di uptime

Parametri di query

limit – Risultati per pagina (1-500, predefinito 50)

offset – Salta N risultati (predefinito 0)

check_type – Filtro: http, ssl, domain, email, pagespeed

days – Periodo di calcolo dell'uptime (1-365, predefinito 30)

A Avvisi

Metodo	Endpoint	Descrizione
GET	/api/v1/alerts	Elenco degli avvisi recenti (paginato)
GET	/api/v1/alerts/:id	Ottieni singolo avviso

I Incidenti

Metodo	Endpoint	Descrizione
GET	/api/v1/incidents	Elenco incidenti (filtro: `?status=open`)
PATCH	/api/v1/incidents/:id/acknowledge	Prendi in carico l'incidente
PATCH	/api/v1/incidents/:id/resolve	Risolvi incidente

Esempio: Risolvi un incidente

curl -X PATCH https://siteguardian.io/api/v1/incidents/:id/resolve \
  -H "Authorization: Bearer sg_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "note": "Fixed the DNS configuration" }'

K Chiavi API

Metodo	Endpoint	Descrizione
POST	/api/v1/api-keys	Genera nuova chiave API (restituita una sola volta)
GET	/api/v1/api-keys	Elenco chiavi API (solo prefisso)
DELETE	/api/v1/api-keys/:id	Revoca chiave API

Importante: La chiave API completa viene restituita una sola volta al momento della creazione. Conservarla in modo sicuro – viene memorizzato solo l'hash.

Tipi di avviso

Tipo	Descrizione
down	Il monitor è non attivo (errore HTTP o timeout)
recovered	Il monitor si è ripristinato dal periodo di inattività
ssl_expiring	Il certificato SSL scade entro la soglia
domain_expiring	Il dominio scade entro la soglia
response_time	Anomalia del tempo di risposta rilevata
email_blacklisted	IP presente nella blacklist DNS
email_issues	Problema critico di salute e-mail (SPF/DKIM/DMARC)

Codici di stato HTTP

Codice	Significato
200	Successo
201	Risorsa creata
400	Richiesta non valida (input non valido)
401	Non autorizzato (chiave API mancante o non valida)
403	Vietato (limite del piano raggiunto)
404	Risorsa non trovata
429	Limite di frequenza superato