Skip to main content
GET
/
certificates
List Certificates
curl --request GET \
  --url https://api.example.com/certificates

Request

curl https://api.certwatch.app/v1/certificates \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

ParameterTypeDescription
statusstringFilter by status: valid, expiring, expired, error
limitintegerNumber of results (default: 50, max: 100)
offsetintegerPagination offset

Example with Filters

curl "https://api.certwatch.app/v1/certificates?status=expiring&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "cert_abc123",
      "domain": "example.com",
      "name": "Main Website",
      "status": "valid",
      "daysUntilExpiry": 45,
      "expiresAt": "2025-02-15T15:00:00Z",
      "issuedAt": "2024-02-15T15:00:00Z",
      "issuer": "Let's Encrypt",
      "subject": "example.com",
      "alertThresholds": [30, 14, 7, 3, 1],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-08T12:00:00Z"
    },
    {
      "id": "cert_def456",
      "domain": "api.example.com",
      "name": "API Server",
      "status": "expiring",
      "daysUntilExpiry": 7,
      "expiresAt": "2025-01-15T10:00:00Z",
      "issuedAt": "2024-01-15T10:00:00Z",
      "issuer": "DigiCert",
      "subject": "api.example.com",
      "alertThresholds": [30, 14, 7, 3, 1],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-08T12:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "requestId": "req_xyz789"
  }
}

Response Fields

FieldTypeDescription
idstringUnique certificate identifier
domainstringDomain being monitored
namestringOptional friendly name
statusstringCurrent status
daysUntilExpiryintegerDays until certificate expires
expiresAtstringExpiration date (ISO 8601)
issuedAtstringIssue date (ISO 8601)
issuerstringCertificate Authority
subjectstringCertificate subject
alertThresholdsarrayConfigured alert days
createdAtstringWhen added to CertWatch
updatedAtstringLast update time

Errors

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid"
  }
}

429 Rate Limited

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 30 seconds."
  }
}