Certificates API

Access detailed SSL certificate information for your monitored domains. Track certificate expiration, view certificate chains, and monitor certificate history.

Overview

The Certificates API provides comprehensive access to SSL certificate data including issuer details, validity periods, certificate chains, and expiration tracking. Use these endpoints to build certificate management dashboards and automated monitoring systems.

Certificate data is populated from SSL scans. Ensure your domain has completed at least one scan before querying certificate endpoints.

Endpoints

GET /api/v1/certificates

List Certificates

Retrieve a paginated list of all certificates for your monitored domains with current status and expiry information.

Query Parameters

Parameter Type Description
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Items per page, max 100 (default: 20)
expiring_soon integer Optional Filter certificates expiring within N days
expired boolean Optional Filter to show only expired certificates (true/false)
sort string Optional Sort field: expiry, grade, hostname (default: expiry)
order string Optional Sort order: asc, desc (default: asc)

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/certificates?expiring_soon=30&sort=expiry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "certificates": [
    {
      "issuer": "Let's Encrypt Authority X3",
      "subject": "example.com",
      "valid_from": "2024-12-15T00:00:00",
      "valid_to": "2025-03-15T12:00:00",
      "serial": "03:AB:CD:EF:12:34:56:78",
      "fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90",
      "days_until_expiry": 62,
      "is_expired": false,
      "lifetime_days": 90,
      "domain": {
        "id": 1,
        "hostname": "example.com",
        "port": 443,
        "name": "Main Website"
      },
      "scan_id": 456,
      "grade": "A+",
      "score": 100,
      "scanned_at": "2025-01-12T10:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /api/v1/domains/{domain_id}/certificate

Get Domain Certificate

Retrieve detailed certificate information for a specific domain including security features like HSTS and OCSP stapling.

Path Parameters

Parameter Type Description
domain_id integer Required Path The unique domain ID

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/domains/1/certificate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "domain": {
    "id": 1,
    "hostname": "example.com",
    "port": 443,
    "name": "Main Website"
  },
  "certificate": {
    "issuer": "Let's Encrypt Authority X3",
    "subject": "example.com",
    "valid_from": "2024-12-15T00:00:00",
    "valid_to": "2025-03-15T12:00:00",
    "serial": "03:AB:CD:EF:12:34:56:78",
    "fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90",
    "days_until_expiry": 62,
    "is_expired": false,
    "lifetime_days": 90
  },
  "security_features": {
    "hsts": true,
    "ocsp_stapling": true,
    "certificate_transparency": true
  },
  "grade": "A+",
  "score": 100,
  "scan_id": 456,
  "scanned_at": "2025-01-12T10:30:00"
}
GET /api/v1/domains/{domain_id}/certificate/history

Get Certificate History

Track certificate changes over time including renewals, issuer changes, and expiry date updates.

Path Parameters

Parameter Type Description
domain_id integer Required Path The unique domain ID

Query Parameters

Parameter Type Description
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Items per page, max 100 (default: 20)
from_date string Optional Filter scans from this date (ISO 8601 format)
to_date string Optional Filter scans until this date (ISO 8601 format)

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/domains/1/certificate/history?from_date=2024-12-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "domain": {
    "id": 1,
    "hostname": "example.com",
    "port": 443,
    "name": "Main Website"
  },
  "history": [
    {
      "issuer": "Let's Encrypt Authority X3",
      "subject": "example.com",
      "valid_from": "2024-12-15T00:00:00",
      "valid_to": "2025-03-15T12:00:00",
      "serial": "03:AB:CD:EF:12:34:56:78",
      "fingerprint": "AB:CD:EF:12:34:56:78:90",
      "days_until_expiry": 62,
      "is_expired": false,
      "scan_id": 456,
      "scanned_at": "2025-01-12T10:30:00",
      "grade": "A+",
      "score": 100,
      "certificate_changed": false
    },
    {
      "issuer": "Let's Encrypt Authority X3",
      "subject": "example.com",
      "valid_from": "2024-09-15T00:00:00",
      "valid_to": "2024-12-15T12:00:00",
      "serial": "02:AB:CD:EF:12:34:56:78",
      "fingerprint": "98:76:54:32:10:FE:DC:BA",
      "days_until_expiry": -28,
      "is_expired": true,
      "scan_id": 123,
      "scanned_at": "2024-12-01T08:00:00",
      "grade": "A",
      "score": 95,
      "certificate_changed": true
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /api/v1/certificates/expiring

Get Expiring Certificates

Get a summary of certificates grouped by expiry timeframe. Useful for building expiry dashboards and alert systems.

Pro tip: Use this endpoint to build automated alerts for certificate renewals. Check daily for certificates expiring within 30 days.

Query Parameters

Parameter Type Description
days integer Optional Custom threshold in days (default: 30)

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/certificates/expiring?days=90" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "summary": {
    "total_domains": 5,
    "expired": 1,
    "expiring_7_days": 1,
    "expiring_30_days": 2,
    "expiring_custom_days": 1
  },
  "expired": [
    {
      "domain_id": 3,
      "hostname": "old-site.com",
      "port": 443,
      "name": "Legacy Site",
      "cert_valid_to": "2025-01-01T00:00:00",
      "days_until_expiry": -12,
      "issuer": "Let's Encrypt",
      "grade": "F"
    }
  ],
  "expiring_7_days": [
    {
      "domain_id": 2,
      "hostname": "urgent.example.com",
      "port": 443,
      "name": "Urgent Renewal",
      "cert_valid_to": "2025-01-18T00:00:00",
      "days_until_expiry": 5,
      "issuer": "DigiCert",
      "grade": "A"
    }
  ],
  "expiring_30_days": [...],
  "expiring_custom_days": [...],
  "threshold_days": 90
}
GET /api/v1/domains/{domain_id}/certificate/chain

Get Certificate Chain

Retrieve the full certificate chain including leaf, intermediate, and root certificates with validation status.

Path Parameters

Parameter Type Description
domain_id integer Required Path The unique domain ID

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/domains/1/certificate/chain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "domain": {
    "id": 1,
    "hostname": "example.com",
    "port": 443,
    "name": "Main Website"
  },
  "chain": [
    {
      "position": 1,
      "type": "leaf",
      "common_name": "example.com",
      "issuer": "R3",
      "valid_from": "2024-12-15T00:00:00Z",
      "valid_to": "2025-03-15T00:00:00Z",
      "serial": "03:AB:CD:EF:12:34:56:78",
      "fingerprint_sha256": "AB:CD:EF:...",
      "signature_algorithm": "SHA256withRSA",
      "key_size": "2048",
      "trust_status": "OK"
    },
    {
      "position": 2,
      "type": "intermediate",
      "common_name": "R3",
      "issuer": "ISRG Root X1",
      "valid_from": "2020-09-04T00:00:00Z",
      "valid_to": "2025-09-15T16:00:00Z",
      "serial": "91:2B:08:4A:CF:0C:18:A7:53:F6:D6:2E:25:A7:5F:5A",
      "fingerprint_sha256": "67:AD:D1:16:6B:...",
      "signature_algorithm": "SHA256withRSA",
      "key_size": "2048",
      "trust_status": "OK"
    },
    {
      "position": 3,
      "type": "root",
      "common_name": "ISRG Root X1",
      "issuer": "ISRG Root X1",
      "valid_from": "2015-06-04T11:04:38Z",
      "valid_to": "2035-06-04T11:04:38Z",
      "serial": "82:10:CF:B0:D2:40:E3:59:44:63:E0:BB:63:82:8B:00",
      "fingerprint_sha256": "96:BC:EC:06:26:...",
      "signature_algorithm": "SHA256withRSA",
      "key_size": "4096",
      "trust_status": "OK"
    }
  ],
  "chain_valid": true,
  "chain_issues": [],
  "total_certificates": 3,
  "scan_id": 456,
  "scanned_at": "2025-01-12T10:30:00"
}
GET /api/v1/certificates/stats

Get Certificate Statistics

Get aggregate statistics about your certificates including counts by issuer and expiry distribution.

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/certificates/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "total_certificates": 25,
  "expired_certificates": 2,
  "valid_certificates": 23,
  "average_days_until_expiry": 67.5,
  "issuers": [
    { "name": "Let's Encrypt Authority X3", "count": 15 },
    { "name": "DigiCert Inc", "count": 6 },
    { "name": "Sectigo Limited", "count": 4 }
  ],
  "expiry_distribution": {
    "expired": 2,
    "within_7_days": 1,
    "within_30_days": 3,
    "within_90_days": 8,
    "beyond_90_days": 11
  }
}

Error Codes

Certificate-specific error codes you may encounter:

Code Message Description
404 Domain not found The specified domain does not exist or you don't have access
404 No completed scans found The domain has not been scanned yet. Trigger a scan first.
404 Certificate chain data not available No scan with certificate chain data found for this domain
400 Invalid date format Date parameters must be in ISO 8601 format

Related Endpoints

Domains API

Manage your monitored domains

Scans API

Trigger and retrieve SSL scans