GET /api/ssl-check

SSL Check

Inspect the TLS certificate for any hostname. Opens a TLS connection to port 443 and returns the presented certificate details as clean JSON - subject, issuer, validity dates, days remaining, and subject alternative names. The certificate.validfield means only that the current time is within the certificate's valid_from and valid_to date range; it does not mean the certificate chain is trusted by the system or that hostname verification has passed. Results are cached for 60 seconds.

Query parameters

hostnamerequiredThe hostname to inspect, e.g. example.com. Do not include a scheme or path.

Example request

curl

curl "https://tinyutils.dev/api/ssl-check?hostname=example.com"

JavaScript (fetch)

const res = await fetch(
  "https://tinyutils.dev/api/ssl-check?hostname=example.com"
);
const data = await res.json();

Example response

{
  "ok": true,
  "hostname": "example.com",
  "normalizedHostname": "example.com",
  "certificate": {
    "valid": true,
    "subject": "CN=example.com",
    "issuer": "DigiCert Inc",
    "valid_from": "2026-01-01T00:00:00.000Z",
    "valid_to": "2026-12-31T23:59:59.000Z",
    "days_remaining": 271,
    "sans": ["example.com", "www.example.com"]
  },
  "meta": {
    "lookupTimeMs": 84,
    "cached": false,
    "rateLimitedScope": "global"
  },
  "error": null
}

Error response

{
  "ok": false,
  "error": "TLS_HANDSHAKE_FAILED",
  "meta": {
    "lookupTimeMs": 312,
    "cached": false,
    "rateLimitedScope": "global"
  }
}

Error codes

INVALID_HOSTNAMEThe hostname is missing or malformed.

BLOCKED_HOSTNAMEThe hostname is private, reserved, or internal.

TLS_TIMEOUTThe TLS connection timed out.

TLS_HANDSHAKE_FAILEDThe TLS handshake failed.

CERT_NOT_PRESENTNo certificate could be read from the connection.

RATE_LIMITEDThe shared request limit was exceeded.

INTERNAL_ERRORAn unexpected server error occurred.

Rate limiting

Requests are rate-limited via a global pool shared with url-check, dns-lookup, url-resolve, and http-headers. Results are cached for 60 seconds to reduce duplicate requests. When the limit is exceeded, the endpoint returns HTTP 429 with RATE_LIMITED.