Riferimento API CertH — Endpoint, parametri ed esempi
Riferimento API CertH completo: endpoint di scan, storico, classifica, monitoraggio e alert, con auth, limiti, codici di errore ed esempi curl.
/api/scan
Scansione immediata di qualsiasi dominio: voto, punteggio, fattori e info certificato; persistita con limitazione.
curl -X POST https://certh.csr.plus/api/scan -H "Content-Type: application/json" -d '{"domain":"stripe.com"}'
/api/public/domains/:domain/history
Storico punteggi per i domini in classifica: 45 giorni gratuiti, la chiave API sblocca di più (Pro 90 / Agency 365).
curl "https://certh.csr.plus/api/public/domains/notion.so/history?days=90" -H "x-api-key: ch_xxx"
/api/leaderboard
Classifiche globali di salute TLS con parametri page, pageSize, sort, grade e q.
curl "https://certh.csr.plus/api/leaderboard?page=1&pageSize=50&sort=score&grade=A%2B"
/api/domain/:domain
Ultimo stato scansionato di un dominio (una riga latest_snapshot).
curl https://certh.csr.plus/api/domain/stripe.com
/api/plans
Elenco dei piani con i limiti di capacità free / Pro / Agency.
curl https://certh.csr.plus/api/plans
/api/me
Utente corrente, piano e chiave API.
curl -b cookie.txt https://certh.csr.plus/api/me
/api/domains
Gestione dei domini monitorati (aggiunta, elenco, rimozione; l'aggiunta scansiona subito).
curl -X POST https://certh.csr.plus/api/domains -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" -d '{"domain":"example.com"}'
/api/domains/:domain/history|events
Snapshot di cronologia privati ed eventi di modifica (alert, rotazioni, ecc.) per i tuoi domini.
curl "https://certh.csr.plus/api/domains/example.com/history?days=90" -H "Authorization: Bearer <jwt>"
/api/ingest
Segnala i risultati di scan propri (piani avanzati) nello stesso pipeline di monitoraggio.
curl -X POST https://certh.csr.plus/api/ingest -H "x-api-key: ch_xxx" -H "Content-Type: application/json" -d '{"domain":"example.com","result":{...}}'
/api/discover
Scoperte dai log CT (nuovi sottodomini / certificati).
curl https://certh.csr.plus/api/discover -H "Authorization: Bearer <jwt>"
/api/alert-rules
Gestione delle regole di alert per cali di voto, scadenza, rotazioni e altro.
curl -X POST https://certh.csr.plus/api/alert-rules -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" -d '{"domain":"example.com","type":"GRADE_CHANGE","target":"you@x.com"}'
Limiti e politica dei dati
- Le query pubbliche vengono persistite: ≤20 nuovi domini per IP al giorno; al massimo 1 snapshot per dominio all'ora.
- Conservazione: i dati di classifica (system) conservati ≥365 giorni; il livello gratuito tronca a 45 giorni.
- Badge: cache edge 1 ora (max-age=3600); qualsiasi parametro query bypassa la cache.
- Codici di errore: 400 parametri non validi / 401 non autenticato / 403 vietato o limite / 404 nessun dato / 422 scan fallito / 429 limite raggiunto.
Domande frequenti
Quanto storico ottengono gli utenti gratuiti?
Gli utenti gratuiti ottengono 45 giorni di storico senza registrazione; Pro sblocca 90 giorni e Agency 365 giorni tramite chiave API.
Dove ottengo una chiave API?
Accedi alla dashboard e una chiave con prefisso ch_ viene generata automaticamente; inviala tramite header x-api-key o parametro ?api_key.
Le query vengono persistite nel database?
Le query pubbliche vengono persistite con limitazione: la prima scansione crea il record, le successive aggiungono allo storico (al massimo 1 volta per dominio all'ora).