API

A free JSON API with no registration. Use it from Ansible, CI pipelines or monitoring scripts.

`GET /api/v1/check`

Parameter	Description
`host`	Required. Hostname
`port`	Default 443
`min_days`	pass only if every server has at least this many days left
`expect_not_after_gt`	pass only if every server's expiry is later than this (RFC3339 or YYYY-MM-DD). Pass the old expiry to confirm a renewal
`expect_fingerprint_sha256`	pass only if every server presents this certificate (SHA-256 fingerprint, colons allowed). Confirms that the exact certificate you deployed is live on every node. Comma-separate several for RSA+ECDSA setups
`nocache`	1 to bypass the cache (costs 3 requests; a target is rescanned at most every 30 s)

Response

{
  "host": "example.com",
  "port": 443,
  "checked_at": "2026-11-11T03:00:00Z",
  "status": "OK",
  "min_days_remaining": 187,
  "earliest_not_after": "2027-05-20T00:00:00Z",
  "all_endpoints_match": true,
  "endpoints": [ { "ip": "192.0.2.10", "fingerprint_sha256": "AB:CD:…", "days_remaining": 187, "lifetime_ratio": 0.93, "chain_valid": true, "hostname_match": true, … } ],
  "result": "pass",
  "reasons": [],
  "cached": false,
  "history": { "renewed": true, "previous": { "earliest_not_after": "2027-03-20T00:00:00Z", … } }
}

status: OK / RENEW_DUE / MISMATCH / CRITICAL / INVALID / EXPIRED / ERROR

result is fail for ERROR, EXPIRED, INVALID or MISMATCH, or when a supplied condition is not met.

`POST /api/v1/scan` / `GET /api/v1/scan`

Configuration scan (protocols, cipher suites, HSTS, CAA, grade). POST starts a scan (HTTP 202); GET returns the latest one. It takes tens of seconds until status becomes done. Starting is limited to 5 per hour and 20 per day per client IP; results for a target are reused for one hour.

curl -fsS -X POST "https://sslcheck.nakayumc.com/api/v1/scan?host=example.com"
sleep 60
curl -fsS "https://sslcheck.nakayumc.com/api/v1/scan?host=example.com" | jq '.status, .result.grade, .result.findings'

Rate limits

Per client IP (IPv6 per /64): 20 requests/minute and 500/day. Exceeding returns HTTP 429 with Retry-After. Results are cached for 5 minutes.

Examples

curl -fsS "https://sslcheck.nakayumc.com/api/v1/check?host=example.com&min_days=30&nocache=1" | jq -e '.result == "pass"'

- name: Verify renewed certificate
  ansible.builtin.uri:
    url: "https://sslcheck.nakayumc.com/api/v1/check?host={{ cert_fqdn }}&min_days=30&nocache=1"
    return_content: true
  register: cert_check
  until: cert_check.json.result == 'pass'
  retries: 5
  delay: 30
  delegate_to: localhost
  run_once: true
  changed_when: false

Status badge

![TLS cert](https://sslcheck.nakayumc.com/badge/example.com.svg)

API

GET /api/v1/check