SSL/TLS Certificates API v2

https://api.codepunch.com/tlscerts/v2

Search certificate records sourced from Certificate Transparency data, filter them by date and hour, retrieve recent records after a configurable settling gap, and fetch parsed certificate detail by result ID.

The v2 API returns JSON. Authenticate through the standard API v2 flow described in the API v2 overview, then use the returned token in the request path.

Keyword filtering is supported, but this reference intentionally does not promise wildcard/operator syntax or a specific indexed-field scope. Use plain search terms unless your integration has separately verified additional search behaviour.

Search Certificates

GET /{token}/certificates

Search certificate rows using an exact date or date comparison, optional keyword filtering, sorting, and offset pagination. Results include certificate identifiers and metadata such as subject CN, issuer CN, serial number, validity timestamps, SHA-256 thumbprint, recorded time, and Subject Alternative Names.

Parameters

date string optional

yyyymmdd, today, yesterday, or all. Default is the API server's current date. all removes the date predicate; it does not disable sorting.

dcm enum optional

Date comparison mode: eq, lt, lte, gt, or gte. Default eq. Non-eq comparisons use midnight UTC for the selected date.

hour enum optional

h0 through h23 selects one UTC hour for an exact-date query. Default h24 keeps the full-day interval unless tillhour is used.

tillhour enum optional

With dcm=eq, a specific date, and hour=h24, values h1 through h24 select the interval from midnight UTC up to that hour.

kw string optional

Optional keyword filter passed to the certificate search index. Use plain terms unless additional search syntax has been separately verified for your integration.

dts enum optional

valid_from or recorded_at. Default valid_from. This selects the field used by the date predicate; it does not automatically change the sort key. To sort by recorded time, use sorton=added_at.

dm enum optional

Use dm=stats to return the matching count in records without the normal data page.

sorton enum optional

Sort by valid_from, valid_to, id, added_at, issuer_cn, subject_cn, cert_serial, or thumprint_sha_256. serial is accepted as an alias for cert_serial. Default valid_from.

sortorder enum optional

asc or desc. Default desc.

start integer optional

Zero-based result offset. Default 0.

limit integer optional

Requested page size. Default 500; use positive values up to 5000.

Date-window examples

# Full UTC day using valid-from time.
GET .../certificates?date=20260911&start=0&limit=500

# One UTC hour.
GET .../certificates?date=20260911&hour=h6&start=0&limit=500

# Midnight through 06:00 UTC.
GET .../certificates?date=20260911&hour=h24&tillhour=h6&start=0&limit=500

# Filter by recorded time and sort by recorded time.
GET .../certificates?date=20260911&dts=recorded_at&sorton=added_at&sortorder=desc

Representative response shape

{
  "status":    true,
  "records":   1,
  "start":     0,
  "limit":     500,
  "sorton":    "valid_from",
  "sortorder": "desc",
  "data": [
    {
      "id":                      18166211,
      "serial":                  "04A1...",
      "subject_cn":              "example.com",
      "issuer_cn":               "Example CA",
      "valid_from":              1789084800,
      "valid_to":                1796860800,
      "valid_from_date_time":    "2026-09-11 00:00:00 UTC",
      "valid_to_date_time":      "2026-12-10 00:00:00 UTC",
      "thumprint_sha_256":       "f62a6e...",
      "recorded_at":             1789084920,
      "recorded_at_date_time":   "2026-09-11 00:02:00 UTC",
      "subject_alt_name":        ["example.com", "www.example.com"]
    }
  ]
}

The integer fields valid_from, valid_to, and recorded_at are Unix timestamps. Their corresponding *_date_time fields are formatted in the API server timezone. The v2 wire field is spelled thumprint_sha_256.

Counts and Pagination

Normal certificate searches and stats mode use the same records field for different purposes, so check the selected data mode.

normal mode

records is the number of rows in the current returned page. Use start and limit to request additional pages.

dm=stats

records is the matching count for the same keyword/date predicate. The response omits the normal data page and removes start/limit.

zero matches

A successful normal search can return records=0, data=[], and status=false without an error field. Client code should treat an explicit error as failure rather than assuming every status=false certificate-search response is an error.

# Count a filtered result set.
GET .../certificates?date=20260911&kw=example&dm=stats

# Request the first page using the same filters.
GET .../certificates?date=20260911&kw=example&start=0&limit=500

This reference does not publish a deep-offset or full-dataset traversal guarantee. Design bulk consumers around the documented page controls and the result range your integration has verified.

Recent Certificates

GET /{token}/recent

Returns the newest qualifying certificate rows that are older than a configurable settling gap. This endpoint does not implement a rolling "last N hours" window: there is no lower time bound.

With the default timegap=2, the query excludes rows whose selected timestamp is within the newest two hours, then returns the newest qualifying rows older than that cutoff.

timegap integer optional

Settling/exclusion gap in hours. Default 2; accepted range 0 through 168. The response reports timegap in seconds.

limit integer optional

Number of rows to return. Default 50; values are constrained to 10 through 5000. This endpoint has no start offset.

kw string optional

Optional keyword filter. Non-empty values shorter than three characters are ignored and produce a warning.

dts enum optional

valid_from or recorded_at. Default valid_from. recorded_at uses the certificate-recorded timestamp for the cutoff and ordering.

itc integer optional

Duration-filter control. Default 1 applies the current v2 filter valid_to - valid_from > 100000 seconds. Set itc=0 to disable that filter.

Each item is returned under certificates with subject_cn, SAN-derived hostnames, validity and recorded timestamps/UTC strings, issuer, serial, and thumprint_sha_256. The current v2 hostnames array should not be assumed to include subject_cn unless that name is also present in SAN data.

GET .../recent?timegap=2&limit=50&dts=recorded_at

{
  "status":      true,
  "date_source": "recorded_at",
  "timegap":     7200,
  "records":     1,
  "certificates": [
    {
      "hostnames":       ["www.example.com"],
      "subject_cn":      "example.com",
      "valid_from_ts":  1789084800,
      "valid_from":     "2026-09-11 00:00:00 GMT",
      "issuer_cn":      "Example CA",
      "serial":         "04A1...",
      "recorded_at_ts": 1789084920,
      "recorded_at":    "2026-09-11 00:02:00 GMT"
    }
  ]
}

The response also exposes records_from_time near the cutoff. Because the query has no lower bound, do not interpret that field as the beginning of a returned rolling window.

Certificate Detail

GET /{token}/certificate/{id}

Use the id returned by /certificates to retrieve parsed certificate detail. The v2 handler uses the indexed row to locate the original Certificate Transparency entry and can return either an X.509 certificate or a precertificate.

The top-level certificate array contains items shaped as ["x509"|"precert", parsed_certificate]. Parsed detail comes from OpenSSL certificate parsing and is augmented with validFrom_date_time, validTo_date_time, thumprint_sha_256, and the PEM-encoded certificate.

Detail retrieval depends on the original CT log entry being available. Inspect each returned certificate item as well as the top-level status: a located row whose CT entry cannot be fetched can be represented as an item with "Error": "Not found".