Documentation

CertNotify API

Read and manage your monitored domains programmatically. Available on Pro and above. The base URL is https://www.certnotify.com/api/v1.

Authentication

Create a key in Settings. It is shown once and stored only as a hash, so it cannot be recovered afterwards — if you lose it, revoke it and make another.

curl https://www.certnotify.com/api/v1/me \
  -H "Authorization: Bearer cn_live_your_key_here"

X-API-Key works too. Keys carry either read or read,write; anything that changes state needs write. Revoking takes effect immediately.

Keys begin with cn_live_ so they are recognisable in a diff or a log. CertNotify’s own secret scanner has a rule for this prefix, so a key committed to a repository you have connected will be flagged.

Rate limits

120 requests per minute per key. Exceeding it returns 429 with code: "rate_limited". The limit is per key rather than per address, so one busy integration cannot throttle another.

Endpoints

GET/v1/merequires read

Confirms a key works and reports the plan, its domain limit and current usage. The first call worth making.

GET/v1/domainsrequires read

Lists your monitored domains, newest first. Takes limit (max 200, default 50) and offset.

curl "https://www.certnotify.com/api/v1/domains?limit=10" \
  -H "Authorization: Bearer cn_live_your_key_here"

{
  "data": [
    {
      "id": "…",
      "domain": "example.com",
      "monitoring": "both",
      "ssl": {
        "valid": true,
        "expiresAt": "2026-12-01T00:00:00.000Z",
        "daysRemaining": 66,
        "status": "healthy",
        "issuer": "Let's Encrypt",
        "tlsVersion": "TLSv1.3"
      },
      "registration": { "…": "…" },
      "riskScore": 20,
      "uptime": "up",
      "lastCheckedAt": "2026-09-26T00:00:00.000Z"
    }
  ],
  "pagination": { "total": 44, "limit": 10, "offset": 0, "hasMore": true }
}

status is one of healthy, warning (30 days), critical (7 days), expired, or unknown when nothing has been checked yet. Those are the same thresholds the dashboard and the alert emails use.

GET/v1/domains/{'{id}'}requires read

One domain. Returns 404 for an id you do not own — deliberately the same answer as one that does not exist.

POST/v1/domainsrequires write

Starts monitoring a domain. Body: { "domain": "example.com", "type": "both" }, where type is ssl, domain or both.

curl -X POST https://www.certnotify.com/api/v1/domains \
  -H "Authorization: Bearer cn_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","type":"both"}'

The first check runs on the next scheduled pass, so certificate fields are null until then. A domain resolving to a private or reserved address is refused.

DELETE/v1/domains/{'{id}'}requires write

Stops monitoring and deletes the history. Irreversible — re-adding gives a new id and an empty history.

Errors

Every error has the same shape, so you can branch on error.code rather than parsing prose.

{ "error": { "code": "insufficient_scope", "message": "This key is read-only." } }

400invalid_requestThe body or a parameter is wrong.

401unauthorizedMissing, malformed, unknown or revoked key.

403plan_requiredThe account is no longer on a plan that includes the API.

403insufficient_scopeThe key is read-only.

403limit_reachedThe plan’s domain limit is reached.

404not_foundNo such resource, or not yours.

409already_existsThat domain is already monitored.

429rate_limitedMore than 120 requests in a minute.

Versioning

The version is in the path. Fields may be added to a response without a new version, so parse defensively and ignore what you do not recognise. Anything removed or renamed gets a new version, and /v1 keeps working.