CertH API Reference — Endpoints & Examples
Complete CertH SSL API reference: scan, score history, leaderboard, monitoring and alert endpoints with auth, rate limits, error codes and curl examples.
/api/scan
Instant scan for any domain: grade, score, factors and certificate info; persisted under throttling.
curl -X POST https://certh.csr.plus/api/scan -H "Content-Type: application/json" -d '{"domain":"stripe.com"}'
/api/public/domains/:domain/history
Score history for leaderboard domains: 45 days free, API Key unlocks more (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
Global TLS health rankings with page, pageSize, sort, grade and q params.
curl "https://certh.csr.plus/api/leaderboard?page=1&pageSize=50&sort=score&grade=A%2B"
/api/domain/:domain
Latest snapshot for a domain (single latest_snapshot row).
curl https://certh.csr.plus/api/domain/stripe.com
/api/plans
Plan list with free / Pro / Agency capability boundaries.
curl https://certh.csr.plus/api/plans
/api/me
Current user, plan and API Key.
curl -b cookie.txt https://certh.csr.plus/api/me
/api/domains
Watched-domain management (add, list, remove; add scans immediately).
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
Private history snapshots and change events (alerts, rotations, etc.) for your domains.
curl "https://certh.csr.plus/api/domains/example.com/history?days=90" -H "Authorization: Bearer <jwt>"
/api/ingest
Report your own scan results (advanced plans) into the same monitoring pipeline.
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
CT-log discoveries (new subdomains / certificates).
curl https://certh.csr.plus/api/discover -H "Authorization: Bearer <jwt>"
/api/alert-rules
Alert rule management for grade drops, expiry, rotations and more.
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"}'
Rate limits & data policy
- Public queries persist: ≤20 new domains per IP daily; at most 1 snapshot per domain per hour.
- Retention: leaderboard (system) data kept ≥365 days; the free API tier truncates to 45 days.
- Badges: edge-cached 1 hour (max-age=3600); append any query param to bypass.
- Errors: 400 bad params / 401 unauthenticated / 403 forbidden or limit / 404 no data / 422 scan failed / 429 rate limited.
FAQ
How much history do free users get?
Free users get 45 days of score history without signup; Pro unlocks 90 days and Agency 365 days via API Key.
Where do I get an API Key?
Sign in at the dashboard and a ch_-prefixed key is generated automatically; send it via the x-api-key header or ?api_key query param.
Do queries persist to the database?
Public queries persist under throttling: the first scan seeds the record, repeated scans append history (at most once per domain per hour).