> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketutils.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSL Scanner

> Inspect a domain's certificate, chain, cipher suite, and expiry window.

Opens a TLS connection to the domain and inspects what it presents: the leaf certificate, the full chain, negotiated protocol version and cipher suite, and a set of validity checks (expiry, hostname match, chain completeness, trust). Rolls up into a security grade.

<Info>
  **1 credit** per call · Typical response time \~220ms
</Info>

## Query parameters

<ParamField query="domain" type="string" required>
  Domain to scan, e.g. `example.com`. No scheme or path — just the hostname.
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Always `true` for a `200` response.
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="domain" type="string" required>
      Echoes the requested domain.
    </ResponseField>

    <ResponseField name="port" type="integer" required>
      Always `443`.
    </ResponseField>

    <ResponseField name="protocol" type="string" required>
      Negotiated protocol, e.g. `"TLSv1.3"`.
    </ResponseField>

    <ResponseField name="certificate" type="object" required>
      <Expandable title="properties">
        <ResponseField name="subject" type="object" required>
          Certificate subject fields (`CN`, `O`, ...).
        </ResponseField>

        <ResponseField name="issuer" type="object" required>
          Issuer fields, same shape as `subject`.
        </ResponseField>

        <ResponseField name="valid_from" type="string" required>
          ISO 8601 timestamp.
        </ResponseField>

        <ResponseField name="valid_to" type="string" required>
          ISO 8601 timestamp.
        </ResponseField>

        <ResponseField name="fingerprint" type="string" required>
          SHA-1 fingerprint.
        </ResponseField>

        <ResponseField name="fingerprint256" type="string" required>
          SHA-256 fingerprint.
        </ResponseField>

        <ResponseField name="serialNumber" type="string" required>
          Certificate serial number.
        </ResponseField>

        <ResponseField name="altNames" type="array" required>
          Subject Alternative Names covered by this certificate.
        </ResponseField>

        <ResponseField name="keySize" type="integer">
          Public key size in bits, when available.
        </ResponseField>

        <ResponseField name="sigalg" type="string">
          Signature algorithm, when available.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="chain" type="array" required>
      Intermediate and root certificates. Each entry has the same shape as `certificate`, minus `keySize` and `sigalg`.
    </ResponseField>

    <ResponseField name="isValid" type="boolean" required>
      `true` if the certificate passes every check below.
    </ResponseField>

    <ResponseField name="daysUntilExpiry" type="integer" required>
      Can be negative for an already-expired certificate.
    </ResponseField>

    <ResponseField name="isExpired" type="boolean" required>
      Whether `valid_to` is in the past.
    </ResponseField>

    <ResponseField name="certValidations" type="object" required>
      <Expandable title="properties">
        <ResponseField name="selfSigned" type="boolean" required>
          `true` if the certificate is its own issuer.
        </ResponseField>

        <ResponseField name="chainComplete" type="boolean" required>
          Whether every intermediate up to a root was presented.
        </ResponseField>

        <ResponseField name="trustedCert" type="boolean" required>
          Whether the chain resolves to a trusted root.
        </ResponseField>

        <ResponseField name="commonNameValid" type="boolean" required>
          Whether the certificate's CN matches the scanned domain.
        </ResponseField>

        <ResponseField name="sanValid" type="boolean" required>
          Whether the domain is covered by a Subject Alternative Name.
        </ResponseField>

        <ResponseField name="chainIssueDescription" type="string">
          Present only when the chain has a problem.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tlsVersion" type="string" required>
      Same value as `protocol`.
    </ResponseField>

    <ResponseField name="cipherSuite" type="string" required>
      Negotiated cipher, e.g. `"TLS_AES_256_GCM_SHA384"`.
    </ResponseField>

    <ResponseField name="securityGrade" type="string" required>
      e.g. `"A+"`, `"A"`, `"B"`, down to `"F"`.
    </ResponseField>

    <ResponseField name="score" type="integer" required>
      0–100, the basis for `securityGrade`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | Cause                                                                      |
| ------ | -------------------------------------------------------------------------- |
| `400`  | `domain` query parameter missing                                           |
| `400`  | Could not connect, the domain doesn't resolve, or the TLS handshake failed |

See the full [error reference](/errors) for the platform-level codes (`401`, `402`, `429`) that apply to every endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.pocketutils.com/v1/ssl-scan?domain=example.com" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.pocketutils.com/v1/ssl-scan?domain=example.com",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.pocketutils.com/v1/ssl-scan",
      params={"domain": "example.com"},
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  data = res.json()["data"]
  ```
</RequestExample>

<ResponseExample>
  ```json Response (abridged) theme={null}
  {
    "success": true,
    "data": {
      "domain": "example.com",
      "port": 443,
      "protocol": "TLSv1.3",
      "certificate": {
        "subject": { "CN": "example.com" },
        "issuer": { "CN": "DigiCert Global G2 TLS RSA SHA256 2020 CA1", "O": "DigiCert Inc" },
        "valid_from": "2026-01-15T00:00:00.000Z",
        "valid_to": "2027-02-15T23:59:59.000Z",
        "fingerprint": "AB:CD:12:34:...",
        "fingerprint256": "12:34:AB:CD:...",
        "serialNumber": "0A1B2C3D4E5F",
        "altNames": ["example.com", "www.example.com"],
        "keySize": 2048,
        "sigalg": "RSA-SHA256"
      },
      "chain": [
        { "subject": { "CN": "DigiCert Global G2 TLS RSA SHA256 2020 CA1" }, "issuer": { "CN": "DigiCert Global Root G2" }, "valid_from": "2021-04-14T00:00:00.000Z", "valid_to": "2031-04-13T23:59:59.000Z", "fingerprint": "...", "fingerprint256": "...", "serialNumber": "..." }
      ],
      "isValid": true,
      "daysUntilExpiry": 209,
      "isExpired": false,
      "certValidations": {
        "selfSigned": false,
        "chainComplete": true,
        "trustedCert": true,
        "commonNameValid": true,
        "sanValid": true
      },
      "tlsVersion": "TLSv1.3",
      "cipherSuite": "TLS_AES_256_GCM_SHA384",
      "securityGrade": "A+",
      "score": 97
    }
  }
  ```
</ResponseExample>


## Related topics

- [Introduction](/index.md)
- [Meta Scanner](/api-reference/meta-scan.md)
- [Rate Limits & Credits](/rate-limits-and-credits.md)