CertiMonitor

API reference

CertiMonitor API

Everything you can do in the dashboard for domains, certificates, alert rules, channels and tags, you can do from a script or CI job. It's a JSON REST API authenticated with API keys.

Base URL
https://certimonitor.com/api/v1
Format
JSON requests and responses, UTF-8, ISO 8601 timestamps in UTC
Auth
Authorization: Bearer cm_live_…

Quick start

  1. Create a key under Settings, API keys with the scopes you need, and keep it in your secret store as CERTIMONITOR_API_KEY.
  2. Add a domain and list what you monitor:
cURL
# Start monitoring a domain
curl -X POST https://certimonitor.com/api/v1/domains \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"example.com"}'

# Every domain with its latest check and current certificate
curl https://certimonitor.com/api/v1/domains \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"

In CI, call Run a check now after deploying a renewed certificate to confirm it's being served.

Authentication

An owner or admin creates keys in Settings. A key belongs to one organization and only sees that organization's data. Send it as a Bearer token on every request.

  • The full key is shown once, when it's created. We store only a hash.
  • A key stops working when it's revoked or expires, or when the person who created it is removed or is no longer an owner or admin.
  • Keys skip two-factor authentication even when your organization requires it for people, so treat a key like a password.

Scopes

Each key has read or write access, or none, per resource. Write includes read. Organization settings, members, billing and API keys can't be changed with a key.

ResourceReadWrite
Domainsdomains:readdomains:write
Certificatescertificates:readcertificates:write
Alert rulesrules:readrules:write
Channelschannels:readchannels:write
Tagstags:readtags:write

Errors

Errors share one shape. error is readable, reason tells apart cases with the same status, and details lists each field a 400 rejected. Quote the requestId if you contact us about a failed request.

400
The body isn't valid JSON or fails validation. details lists each field's problems.
401
Missing, unknown, revoked or expired key, or its creator is no longer an owner or admin (reason: api_key_creator_removed).
402
Your plan's limit, e.g. the number of domains.
403
The key lacks the scope (reason: insufficient_scope), or the endpoint needs a signed-in person (reason: session_only).
404
Not found in your organization.
409
Already exists, e.g. the same hostname and port twice, or a rule change on an item whose rules come from the defaults or a tag (reason: rules_not_custom).
429
Rate limited. Wait for the seconds in the Retry-After header.
{
  "error": "Invalid request",
  "details": {
    "hostname": [
      "Enter a full domain, like example.com"
    ]
  },
  "requestId": "ccd11438-9549-4a9e-8aed-844dc917ea11"
}

Rate limits

Each key can make 300 requests a minute. Running a check has its own limits: 5 per domain every 10 minutes and 60 per organization an hour. Test sends (rules and channels) are limited to 5 a minute per organization, plus per-destination limits on channel tests. Over a limit you get a 429 with a Retry-After header in seconds.

Domains

A domain is a hostname and port to monitor. Each run checks its TLS certificate, its registration and its email records, depending on which checks are on.

List domains

GET/domains

Every monitored domain in the organization, sorted by hostname, with its latest check, current certificate and tags.

API key scope: domains:read

curl https://certimonitor.com/api/v1/domains \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0001xk96example",
    "hostname": "example.com",
    "port": 443,
    "enabled": true,
    "tlsChecks": true,
    "registrationChecks": true,
    "emailChecks": false,
    "httpChecks": true,
    "httpPath": "/",
    "httpExpectedStatus": null,
    "dnsChecks": true,
    "dnsWatch": {
      "NS": "ALERT",
      "MX": "ALERT",
      "CAA": "ALERT",
      "CNAME": "ALERT",
      "TXT": "INFO",
      "A": "OFF",
      "AAAA": "OFF"
    },
    "dnsRecords": {
      "NS": [
        "a.iana-servers.net",
        "b.iana-servers.net"
      ],
      "MX": [
        "0 ."
      ],
      "CAA": [],
      "CNAME": [],
      "TXT": [
        "v=spf1 -all"
      ]
    },
    "dnsCheckedAt": "2026-10-05T08:00:07.000Z",
    "lastCheckedAt": "2026-10-05T08:00:07.000Z",
    "registrationExpiresAt": "2027-08-13T04:00:00.000Z",
    "registrar": "Example Registrar, Inc.",
    "registrationStatuses": [
      "client transfer prohibited"
    ],
    "nameservers": [
      "a.iana-servers.net",
      "b.iana-servers.net"
    ],
    "spfRecord": null,
    "dmarcRecord": null,
    "dkimSelectors": [],
    "createdAt": "2026-09-06T08:00:00.000Z",
    "updatedAt": "2026-10-05T08:00:07.000Z",
    "checks": [
      {
        "status": "HEALTHY",
        "message": null,
        "checkedAt": "2026-10-05T08:00:07.000Z"
      }
    ],
    "certificates": [
      {
        "validTo": "2026-12-04T22:29:38.000Z",
        "chainValidTo": "2026-12-04T22:29:38.000Z",
        "issuer": "C=US, O=Let's Encrypt, CN=R11",
        "subject": "CN=example.com"
      }
    ],
    "tags": [
      {
        "id": "cmuv7k2ab0006xk96tag0001",
        "name": "Production",
        "slug": "production",
        "color": "GREEN"
      }
    ]
  }
]

Add a domain

POST/domains

Starts monitoring a domain. It gets the default alert rules and the organization's default channels, and is checked on the next run. Fails with 402 at the plan's domain limit and 409 if the hostname and port already exist.

API key scope: domains:write

Body parameters

hostnamestringrequired
A full domain like api.example.com, without https:// or a path. Internationalized names are accepted.
portinteger
TLS port, 1–65535. Default 443.
tlsChecksboolean
Check the TLS certificate on the port. Default true.
registrationChecksboolean
Check the domain registration (RDAP): expiry, registrar, transfer lock. Default true.
emailChecksboolean
Check SPF, DKIM and DMARC records, including SPF's DNS lookup limit. Default false.
httpChecksboolean
Uptime: an HTTPS GET of / on each check. A 5xx or no response is down; redirects and 4xx are up. Default true.
httpPathstring
Uptime: the path requested on the domain's own host and port, starting with / (a health endpoint, say /healthz). Query strings allowed; no spaces. PATCH only. Default /.
httpExpectedStatusinteger | null
Uptime: the one HTTP status that counts as up (100–599). Null, the default: any answer below 500 is up. Changing it or httpPath starts the failure count over. PATCH only.
dnsChecksboolean
DNS change detection: the record types in dnsWatch, looked up about daily from two public resolvers (a set counts only when both agree). Every change is recorded and opens a DNS_CHANGED alert. Default false.
dnsWatchobject
How changes to each record type notify: { NS, MX, CAA, CNAME, TXT, A, AAAA } each ALERT (at the DNS_CHANGED rule's severity), INFO (severity INFO) or OFF (not watched). Types left out keep their level; defaults are ALERT for NS, MX, CAA and CNAME, INFO for TXT, OFF for A and AAAA (they rotate behind CDNs).
tagsstring[]
Tag names, up to 10. Missing tags are created.
curl -X POST https://certimonitor.com/api/v1/domains \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"example.com","emailChecks":true,"tags":["client-a"]}'
Response 201
{
  "id": "cmuv7k2ab0001xk96example",
  "hostname": "example.com",
  "port": 443,
  "enabled": true,
  "tlsChecks": true,
  "registrationChecks": true,
  "emailChecks": true,
  "httpChecks": true,
  "httpPath": "/",
  "httpExpectedStatus": null,
  "dnsChecks": true,
  "dnsWatch": {
    "NS": "ALERT",
    "MX": "ALERT",
    "CAA": "ALERT",
    "CNAME": "ALERT",
    "TXT": "INFO",
    "A": "OFF",
    "AAAA": "OFF"
  },
  "dnsRecords": {
    "NS": [
      "a.iana-servers.net",
      "b.iana-servers.net"
    ],
    "MX": [
      "0 ."
    ],
    "CAA": [],
    "CNAME": [],
    "TXT": [
      "v=spf1 -all"
    ]
  },
  "dnsCheckedAt": "2026-10-05T08:00:07.000Z",
  "lastCheckedAt": null,
  "registrationExpiresAt": "2027-08-13T04:00:00.000Z",
  "registrar": "Example Registrar, Inc.",
  "registrationStatuses": [
    "client transfer prohibited"
  ],
  "nameservers": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "spfRecord": null,
  "dmarcRecord": null,
  "dkimSelectors": [],
  "createdAt": "2026-09-06T08:00:00.000Z",
  "updatedAt": "2026-10-05T08:00:07.000Z",
  "tags": []
}

Get a domain

GET/domains/:id

One domain with its alert rules, its current certificate (including its chain) and its latest check. The full histories are under List served certificates and List checks.

API key scope: domains:read

Path parameters

idstringrequired
The domain's id
curl https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
{
  "id": "cmuv7k2ab0001xk96example",
  "hostname": "example.com",
  "port": 443,
  "enabled": true,
  "tlsChecks": true,
  "registrationChecks": true,
  "emailChecks": false,
  "httpChecks": true,
  "httpPath": "/",
  "httpExpectedStatus": null,
  "dnsChecks": true,
  "dnsWatch": {
    "NS": "ALERT",
    "MX": "ALERT",
    "CAA": "ALERT",
    "CNAME": "ALERT",
    "TXT": "INFO",
    "A": "OFF",
    "AAAA": "OFF"
  },
  "dnsRecords": {
    "NS": [
      "a.iana-servers.net",
      "b.iana-servers.net"
    ],
    "MX": [
      "0 ."
    ],
    "CAA": [],
    "CNAME": [],
    "TXT": [
      "v=spf1 -all"
    ]
  },
  "dnsCheckedAt": "2026-10-05T08:00:07.000Z",
  "lastCheckedAt": "2026-10-05T08:00:07.000Z",
  "registrationExpiresAt": "2027-08-13T04:00:00.000Z",
  "registrar": "Example Registrar, Inc.",
  "registrationStatuses": [
    "client transfer prohibited"
  ],
  "nameservers": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "spfRecord": null,
  "dmarcRecord": null,
  "dkimSelectors": [],
  "createdAt": "2026-09-06T08:00:00.000Z",
  "updatedAt": "2026-10-05T08:00:07.000Z",
  "alertRules": [
    {
      "id": "cmuv7k2ab0002xk96rule001",
      "domainId": "cmuv7k2ab0001xk96example",
      "trackedCertificateId": null,
      "type": "TLS_EXPIRY",
      "threshold": 14,
      "severity": "CRITICAL",
      "enabled": true,
      "suppressIfAutoRenew": false,
      "channelIds": [
        "cmuv7k2ab0003xk96channel"
      ],
      "createdAt": "2026-10-05T08:10:00.000Z",
      "updatedAt": "2026-10-05T08:10:00.000Z"
    }
  ],
  "certificates": [
    {
      "id": "cmuv7k2ab0004xk96cert001",
      "domainId": "cmuv7k2ab0001xk96example",
      "issuer": "C=US, O=Let's Encrypt, CN=R11",
      "subject": "CN=example.com",
      "subjectAltNames": [
        "example.com",
        "www.example.com"
      ],
      "serialNumber": "04A1B2C3D4E5F60718293A4B5C6D7E8F",
      "validFrom": "2026-09-05T22:29:39.000Z",
      "validTo": "2026-12-04T22:29:38.000Z",
      "chainValidTo": "2026-12-04T22:29:38.000Z",
      "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
      "autoRenewExpected": true,
      "chain": [
        {
          "subject": "CN=example.com",
          "issuer": "C=US, O=Let's Encrypt, CN=R11",
          "validTo": "2026-12-04T22:29:38.000Z",
          "selfSigned": false,
          "trustedRoot": false
        },
        {
          "subject": "C=US, O=Let's Encrypt, CN=R11",
          "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
          "validTo": "2027-03-12T23:59:59.000Z",
          "selfSigned": false,
          "trustedRoot": false
        },
        {
          "subject": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
          "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
          "validTo": "2035-06-04T11:04:38.000Z",
          "selfSigned": true,
          "trustedRoot": true
        }
      ],
      "firstSeenAt": "2026-09-06T08:00:12.000Z",
      "lastSeenAt": "2026-10-05T08:00:07.000Z"
    }
  ],
  "checks": [
    {
      "id": "cmuv7k2ab0005xk96check01",
      "domainId": "cmuv7k2ab0001xk96example",
      "type": "TLS",
      "status": "HEALTHY",
      "message": null,
      "latencyMs": 42,
      "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
      "trusted": true,
      "checkedAt": "2026-10-05T08:00:07.000Z"
    }
  ],
  "tags": [
    {
      "id": "cmuv7k2ab0006xk96tag0001",
      "name": "Production",
      "slug": "production",
      "color": "GREEN"
    }
  ]
}

Update a domain

PATCH/domains/:id

Change the port, pause monitoring, switch checks on or off, or replace the tags. The hostname can't change. Turning a check off closes its open alerts quietly.

API key scope: domains:write

Path parameters

idstringrequired
The domain's id

Body parameters

portinteger
TLS port, 1–65535.
enabledboolean
false pauses all checks for the domain.
tlsChecksboolean
Check the TLS certificate on the port.
registrationChecksboolean
Check the domain registration (RDAP): expiry, registrar, transfer lock.
emailChecksboolean
Check SPF, DKIM and DMARC records, including SPF's DNS lookup limit.
httpChecksboolean
Uptime: an HTTPS GET of / on each check. A 5xx or no response is down; redirects and 4xx are up.
httpPathstring
Uptime: the path requested on the domain's own host and port, starting with / (a health endpoint, say /healthz). Query strings allowed; no spaces. PATCH only. Default /.
httpExpectedStatusinteger | null
Uptime: the one HTTP status that counts as up (100–599). Null, the default: any answer below 500 is up. Changing it or httpPath starts the failure count over. PATCH only.
dnsChecksboolean
DNS change detection: the record types in dnsWatch, looked up about daily from two public resolvers (a set counts only when both agree). Every change is recorded and opens a DNS_CHANGED alert.
dnsWatchobject
How changes to each record type notify: { NS, MX, CAA, CNAME, TXT, A, AAAA } each ALERT (at the DNS_CHANGED rule's severity), INFO (severity INFO) or OFF (not watched). Types left out keep their level; defaults are ALERT for NS, MX, CAA and CNAME, INFO for TXT, OFF for A and AAAA (they rotate behind CDNs).
tagsstring[]
Tag names; replaces the domain's tags. Missing tags are created, with domains:write alone (no tags:write needed).
curl -X PATCH https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"tags":["Production"]}'
Response 200
{
  "id": "cmuv7k2ab0001xk96example",
  "hostname": "example.com",
  "port": 443,
  "enabled": true,
  "tlsChecks": true,
  "registrationChecks": true,
  "emailChecks": false,
  "httpChecks": true,
  "httpPath": "/",
  "httpExpectedStatus": null,
  "dnsChecks": true,
  "dnsWatch": {
    "NS": "ALERT",
    "MX": "ALERT",
    "CAA": "ALERT",
    "CNAME": "ALERT",
    "TXT": "INFO",
    "A": "OFF",
    "AAAA": "OFF"
  },
  "dnsRecords": {
    "NS": [
      "a.iana-servers.net",
      "b.iana-servers.net"
    ],
    "MX": [
      "0 ."
    ],
    "CAA": [],
    "CNAME": [],
    "TXT": [
      "v=spf1 -all"
    ]
  },
  "dnsCheckedAt": "2026-10-05T08:00:07.000Z",
  "lastCheckedAt": "2026-10-05T08:00:07.000Z",
  "registrationExpiresAt": "2027-08-13T04:00:00.000Z",
  "registrar": "Example Registrar, Inc.",
  "registrationStatuses": [
    "client transfer prohibited"
  ],
  "nameservers": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "spfRecord": null,
  "dmarcRecord": null,
  "dkimSelectors": [],
  "createdAt": "2026-09-06T08:00:00.000Z",
  "updatedAt": "2026-10-05T08:00:07.000Z",
  "tags": [
    {
      "id": "cmuv7k2ab0006xk96tag0001",
      "name": "Production",
      "slug": "production",
      "color": "GREEN"
    }
  ]
}

Delete a domain

DELETE/domains/:id

Stops monitoring and deletes the domain's checks, certificates, rules and alerts.

API key scope: domains:write

Path parameters

idstringrequired
The domain's id
curl -X DELETE https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Import domains

POST/domains/import

Adds up to 500 domains in one request, all or nothing. Every entry gets an outcome: created, exists (already monitored), duplicate (listed twice), invalid (with the reason) or limit (over the plan's domain limit; earlier entries are added first). Domains get the default rules of the checks given, which apply to all of them.

API key scope: domains:write

Body parameters

domainsobject[]required
Up to 500 of { hostname, port?, tags? }, with the fields of Add a domain.
tlsChecksboolean
Check the TLS certificate on the port. Default true.
registrationChecksboolean
Check the domain registration (RDAP): expiry, registrar, transfer lock. Default true.
emailChecksboolean
Check SPF, DKIM and DMARC records, including SPF's DNS lookup limit. Default false.
httpChecksboolean
Uptime: an HTTPS GET of / on each check. A 5xx or no response is down; redirects and 4xx are up. Default true.
httpPathstring
Uptime: the path requested on the domain's own host and port, starting with / (a health endpoint, say /healthz). Query strings allowed; no spaces. PATCH only. Default /.
httpExpectedStatusinteger | null
Uptime: the one HTTP status that counts as up (100–599). Null, the default: any answer below 500 is up. Changing it or httpPath starts the failure count over. PATCH only.
dnsChecksboolean
DNS change detection: the record types in dnsWatch, looked up about daily from two public resolvers (a set counts only when both agree). Every change is recorded and opens a DNS_CHANGED alert. Default false.
dnsWatchobject
How changes to each record type notify: { NS, MX, CAA, CNAME, TXT, A, AAAA } each ALERT (at the DNS_CHANGED rule's severity), INFO (severity INFO) or OFF (not watched). Types left out keep their level; defaults are ALERT for NS, MX, CAA and CNAME, INFO for TXT, OFF for A and AAAA (they rotate behind CDNs).
curl -X POST https://certimonitor.com/api/v1/domains/import \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":[{"hostname":"example.com"},{"hostname":"api.example.com","port":8443,"tags":["client-a"]}]}'
Response 200
{
  "created": 1,
  "results": [
    {
      "index": 0,
      "hostname": "example.com",
      "port": 443,
      "status": "created",
      "id": "cmuv7k2ab0001xk96example"
    },
    {
      "index": 1,
      "hostname": "api.example.com",
      "port": 8443,
      "status": "exists"
    }
  ]
}

Act on many domains

POST/domains/bulk

Pause, resume, delete, or add or remove tags on up to 500 domains at once, all or nothing. Ids that aren't the organization's are ignored. Resuming counts against the plan: if the paused domains don't all fit, none resume (402). Removing a tag a domain follows rules from moves it back to the default rules.

API key scope: domains:write

Body parameters

actionenumrequired
pause, resume, delete, addTags or removeTags
idsstring[]required
1–500 domain ids
tagsstring[]
Required with addTags and removeTags: tag names. Missing tags are created on addTags; a domain can have at most 10.
curl -X POST https://certimonitor.com/api/v1/domains/bulk \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"addTags","ids":["cmuv7k2ab0001xk96example"],"tags":["client-a"]}'
Response 200
{
  "affected": 1
}

Export domains as CSV

GET/domains/export

Every domain matching the filters, as a CSV download: hostname, port, status, status_reason, certificate_expires, days_left, issuer, registration_expires, tags and last_checked. Text cells that would start with =, +, -, @ get a leading apostrophe so spreadsheets don't run them as formulas; numbers (a negative days_left) stay numbers.

API key scope: domains:read

Query parameters

qstring
Matches hostnames, tag names and issuers
statusenum
attention, healthy, warning, critical, error, pending or paused
tagstring
A tag's slug
sortenum
attention (default), name, expiry or checked
curl https://certimonitor.com/api/v1/domains/export \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200

List checks

GET/domains/:id/checks

The 50 most recent check results for a domain, newest first. 404 for a domain outside your organization.

API key scope: domains:read

Path parameters

idstringrequired
The domain's id
curl https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/checks \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0005xk96check01",
    "domainId": "cmuv7k2ab0001xk96example",
    "type": "TLS",
    "status": "HEALTHY",
    "message": null,
    "latencyMs": 42,
    "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
    "trusted": true,
    "checkedAt": "2026-10-05T08:00:07.000Z"
  }
]

List DNS changes

GET/domains/:id/dns-changes

The domain's DNS change history, newest first: each changed record type with its set before and after. Changes from one lookup share its detectedAt. The current records are dnsRecords on the domain. 404 for a domain outside your organization.

API key scope: domains:read

Path parameters

idstringrequired
The domain's id

Query parameters

limitinteger
How many, 1–100. Default 30.
curl https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/dns-changes \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0012xk96dnschg1",
    "domainId": "cmuv7k2ab0001xk96example",
    "recordType": "MX",
    "before": [
      "10 mx1.old-provider.example"
    ],
    "after": [
      "1 smtp.google.com"
    ],
    "detectedAt": "2026-10-05T08:00:07.000Z"
  }
]

Run a check now

POST/domains/:id/check

Checks the domain immediately, for example right after renewing a certificate. Registration and email data younger than a day is reused. Limited to 5 per domain every 10 minutes and 60 per organization an hour.

API key scope: domains:write

Path parameters

idstringrequired
The domain's id
curl -X POST https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/check \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
{
  "certificate": {
    "id": "cmuv7k2ab0004xk96cert001",
    "domainId": "cmuv7k2ab0001xk96example",
    "issuer": "C=US, O=Let's Encrypt, CN=R11",
    "subject": "CN=example.com",
    "subjectAltNames": [
      "example.com",
      "www.example.com"
    ],
    "serialNumber": "04A1B2C3D4E5F60718293A4B5C6D7E8F",
    "validFrom": "2026-09-05T22:29:39.000Z",
    "validTo": "2026-12-04T22:29:38.000Z",
    "chainValidTo": "2026-12-04T22:29:38.000Z",
    "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
    "autoRenewExpected": true,
    "chain": [
      {
        "subject": "CN=example.com",
        "issuer": "C=US, O=Let's Encrypt, CN=R11",
        "validTo": "2026-12-04T22:29:38.000Z",
        "selfSigned": false,
        "trustedRoot": false
      },
      {
        "subject": "C=US, O=Let's Encrypt, CN=R11",
        "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "validTo": "2027-03-12T23:59:59.000Z",
        "selfSigned": false,
        "trustedRoot": false
      },
      {
        "subject": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "validTo": "2035-06-04T11:04:38.000Z",
        "selfSigned": true,
        "trustedRoot": true
      }
    ],
    "firstSeenAt": "2026-09-06T08:00:12.000Z",
    "lastSeenAt": "2026-10-05T08:00:07.000Z"
  },
  "checkResult": {
    "id": "cmuv7k2ab0005xk96check01",
    "domainId": "cmuv7k2ab0001xk96example",
    "type": "TLS",
    "status": "HEALTHY",
    "message": null,
    "latencyMs": 42,
    "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
    "trusted": true,
    "checkedAt": "2026-10-05T08:00:07.000Z"
  },
  "policyResult": {
    "status": "HEALTHY",
    "daysRemaining": 60,
    "trusted": true,
    "expired": false,
    "inRenewalWindow": false,
    "matches": []
  },
  "domainPolicyResult": {
    "status": "HEALTHY",
    "daysRemaining": 312,
    "expired": false,
    "matches": []
  }
}

List served certificates

GET/domains/:id/certificates

The certificates the domain has served, most recently seen first, up to 200. Each has the chain from the last check that saw it (null for certificates seen before chains were stored).

API key scope: certificates:read

Path parameters

idstringrequired
The domain's id
curl https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/certificates \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0004xk96cert001",
    "domainId": "cmuv7k2ab0001xk96example",
    "issuer": "C=US, O=Let's Encrypt, CN=R11",
    "subject": "CN=example.com",
    "subjectAltNames": [
      "example.com",
      "www.example.com"
    ],
    "serialNumber": "04A1B2C3D4E5F60718293A4B5C6D7E8F",
    "validFrom": "2026-09-05T22:29:39.000Z",
    "validTo": "2026-12-04T22:29:38.000Z",
    "chainValidTo": "2026-12-04T22:29:38.000Z",
    "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
    "autoRenewExpected": true,
    "chain": [
      {
        "subject": "CN=example.com",
        "issuer": "C=US, O=Let's Encrypt, CN=R11",
        "validTo": "2026-12-04T22:29:38.000Z",
        "selfSigned": false,
        "trustedRoot": false
      },
      {
        "subject": "C=US, O=Let's Encrypt, CN=R11",
        "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "validTo": "2027-03-12T23:59:59.000Z",
        "selfSigned": false,
        "trustedRoot": false
      },
      {
        "subject": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "issuer": "C=US, O=Internet Security Research Group, CN=ISRG Root X1",
        "validTo": "2035-06-04T11:04:38.000Z",
        "selfSigned": true,
        "trustedRoot": true
      }
    ],
    "firstSeenAt": "2026-09-06T08:00:12.000Z",
    "lastSeenAt": "2026-10-05T08:00:07.000Z"
  }
]

Tracked certificates

Certificates CertiMonitor can't reach over the network, such as Apple push, code signing, SAML or client certificates. Paste the PEM and track its expiry. Private keys are rejected and never stored.

List tracked certificates

GET/certificates

Every tracked certificate in the organization.

API key scope: certificates:read

curl https://certimonitor.com/api/v1/certificates \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0007xk96tracked",
    "name": "Apple push certificate",
    "kind": "APPLE_APNS",
    "notes": "Renew in the Apple Developer portal",
    "subject": "CN=Apple Push Services: com.example.app",
    "issuer": "CN=Apple Worldwide Developer Relations Certification Authority",
    "serialNumber": "5A3F9C21B07E4D11",
    "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
    "subjectAltNames": [],
    "validFrom": "2026-03-01T10:00:00.000Z",
    "validTo": "2027-03-31T10:00:00.000Z",
    "createdAt": "2026-10-05T08:20:00.000Z",
    "updatedAt": "2026-10-05T08:20:00.000Z",
    "tags": []
  }
]

Track a certificate

POST/certificates

Parses the PEM and starts tracking its expiry. The name and kind default from the certificate when left out.

API key scope: certificates:write

Body parameters

certificatestringrequired
The certificate in PEM format (-----BEGIN CERTIFICATE-----). Up to 64 KB.
namestring
Display name, up to 120 characters. Defaults to the certificate's common name.
kindenum
APPLE_MDM_PUSH, APPLE_APNS, APPLE_DEVELOPER, CODE_SIGNING, SAML_SIGNING, CLIENT_AUTH, SMIME, CA or OTHER. Detected when left out.
notesstring
Free text, up to 2000 characters, e.g. how to renew it.
curl -X POST https://certimonitor.com/api/v1/certificates \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"certificate":"-----BEGIN CERTIFICATE-----\nMIIF…\n-----END CERTIFICATE-----","name":"Apple push certificate","notes":"Renew in the Apple Developer portal"}'
Response 201
{
  "id": "cmuv7k2ab0007xk96tracked",
  "name": "Apple push certificate",
  "kind": "APPLE_APNS",
  "notes": "Renew in the Apple Developer portal",
  "subject": "CN=Apple Push Services: com.example.app",
  "issuer": "CN=Apple Worldwide Developer Relations Certification Authority",
  "serialNumber": "5A3F9C21B07E4D11",
  "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
  "subjectAltNames": [],
  "validFrom": "2026-03-01T10:00:00.000Z",
  "validTo": "2027-03-31T10:00:00.000Z",
  "createdAt": "2026-10-05T08:20:00.000Z",
  "updatedAt": "2026-10-05T08:20:00.000Z",
  "tags": []
}

Get a tracked certificate

GET/certificates/:id

One tracked certificate.

API key scope: certificates:read

Path parameters

idstringrequired
The certificate's id
curl https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
{
  "id": "cmuv7k2ab0007xk96tracked",
  "name": "Apple push certificate",
  "kind": "APPLE_APNS",
  "notes": "Renew in the Apple Developer portal",
  "subject": "CN=Apple Push Services: com.example.app",
  "issuer": "CN=Apple Worldwide Developer Relations Certification Authority",
  "serialNumber": "5A3F9C21B07E4D11",
  "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
  "subjectAltNames": [],
  "validFrom": "2026-03-01T10:00:00.000Z",
  "validTo": "2027-03-31T10:00:00.000Z",
  "createdAt": "2026-10-05T08:20:00.000Z",
  "updatedAt": "2026-10-05T08:20:00.000Z",
  "tags": []
}

Update a tracked certificate

PATCH/certificates/:id

Rename it, change its notes or tags, or replace the PEM after a renewal (rules and notes are kept). Replacing it with a certificate for a different subject needs confirmSubjectChange.

API key scope: certificates:write

Path parameters

idstringrequired
The certificate's id

Body parameters

namestring
Display name, up to 120 characters.
kindenum
See Track a certificate.
notesstring | null
Up to 2000 characters; null clears them.
tagsstring[]
Tag names; replaces the certificate's tags. Missing tags are created, with certificates:write alone (no tags:write needed).
certificatestring
The renewed certificate in PEM format.
confirmSubjectChangeboolean
Required when the new certificate's subject differs from the old one.
curl -X PATCH https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"certificate":"-----BEGIN CERTIFICATE-----\nMIIF…\n-----END CERTIFICATE-----"}'
Response 200
{
  "id": "cmuv7k2ab0007xk96tracked",
  "name": "Apple push certificate",
  "kind": "APPLE_APNS",
  "notes": "Renew in the Apple Developer portal",
  "subject": "CN=Apple Push Services: com.example.app",
  "issuer": "CN=Apple Worldwide Developer Relations Certification Authority",
  "serialNumber": "5A3F9C21B07E4D11",
  "fingerprint": "96:10:34:EB:E7:3C:0A:AB:92:EE:5C:12:7A:42:65:B9:9A:BC:36:CD:F0:B5:3B:82:B1:07:88:E0:87:A7:2A:14",
  "subjectAltNames": [],
  "validFrom": "2026-03-01T10:00:00.000Z",
  "validTo": "2028-03-31T10:00:00.000Z",
  "createdAt": "2026-10-05T08:20:00.000Z",
  "updatedAt": "2026-10-05T08:20:00.000Z",
  "tags": []
}

Delete a tracked certificate

DELETE/certificates/:id

Stops tracking it and deletes its rules and alerts.

API key scope: certificates:write

Path parameters

idstringrequired
The certificate's id
curl -X DELETE https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Alert rules

A rule decides when a domain or tracked certificate raises an alert and which channels hear about it. Each item takes its rules from one source, its rule mode: DEFAULT (built-in rules: TLS expiry at 30 days warning and 7 days critical, an invalid certificate, unreachable on two checks in a row, registration expiry at 30 and 7 days, plus SPF and DMARC with email checks on), TAG (the rules of one of its tags, kept in sync) or CUSTOM (its own rules). Rules can only be added, edited or deleted directly in CUSTOM mode; otherwise these return 409 with reason rules_not_custom. An item can have up to 50 rules.

List a domain's rules

GET/domains/:id/rules

The alert rules on one domain, oldest first. 404 for a domain outside your organization.

API key scope: rules:read

Path parameters

idstringrequired
The domain's id
curl https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0002xk96rule001",
    "domainId": "cmuv7k2ab0001xk96example",
    "trackedCertificateId": null,
    "type": "TLS_EXPIRY",
    "threshold": 14,
    "severity": "CRITICAL",
    "enabled": true,
    "suppressIfAutoRenew": false,
    "channelIds": [
      "cmuv7k2ab0003xk96channel"
    ],
    "createdAt": "2026-10-05T08:10:00.000Z",
    "updatedAt": "2026-10-05T08:10:00.000Z"
  }
]

Add a rule to a domain

POST/domains/:id/rules

Adds an alert rule to a domain. Returns 409 with reason rules_not_custom unless the item's rule mode is CUSTOM. 400 once the domain has 50 rules.

API key scope: rules:write

Path parameters

idstringrequired
The domain's id

Body parameters

typeenumrequired
TLS_EXPIRY (certificate expiry), TLS_INVALID (untrusted or mismatched certificate), UNREACHABLE (the TLS connection failed on two checks in a row), HTTP_FAILURE (the site returned a 5xx, or not the expected status, or didn't respond, two checks in a row), HTTP_SLOW (the site answered slower than threshold milliseconds, two checks in a row), DNS_CHANGED (a watched DNS record changed since the last lookup), DOMAIN_EXPIRY (registration expiry), SPF_INVALID (SPF missing, +all, or failing the 10-lookup limit), DMARC_INVALID (DMARC missing or no valid policy) or DKIM_INVALID (no key on common selectors). TLS types and UNREACHABLE need TLS checks on, HTTP_FAILURE and HTTP_SLOW uptime checks, DNS_CHANGED DNS change checks, email types email checks.
thresholdinteger
Required for TLS_EXPIRY, CERT_EXPIRY and DOMAIN_EXPIRY: days before expiry that the rule fires, 0–3650. Required for HTTP_SLOW: the response time in milliseconds it must exceed, 100–9000. Leave null on other types.
severityenum
INFO, WARNING or CRITICAL. Default WARNING. INFO alerts notify but never mark a domain unhealthy, and channels set to critical only skip them; webhooks receive the same three values.
enabledboolean
Default true.
suppressIfAutoRenewboolean
TLS_EXPIRY only (ignored on other types): hold the alert while renewal isn't due yet, for certificates CertiMonitor has seen renew automatically before. It still fires once renewal is overdue.
channelIdsstring[]
Channels to notify, up to 20. Leave out for the organization's default channels.
curl -X POST https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"TLS_EXPIRY","threshold":14,"severity":"CRITICAL"}'
Response 201
{
  "id": "cmuv7k2ab0002xk96rule001",
  "domainId": "cmuv7k2ab0001xk96example",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 14,
  "severity": "CRITICAL",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z"
}

List a certificate's rules

GET/certificates/:id/rules

The alert rules on one tracked certificate, oldest first. 404 for a certificate outside your organization.

API key scope: rules:read

Path parameters

idstringrequired
The certificate's id
curl https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0002xk96rule001",
    "domainId": null,
    "trackedCertificateId": "cmuv7k2ab0007xk96tracked",
    "type": "CERT_EXPIRY",
    "threshold": 30,
    "severity": "WARNING",
    "enabled": true,
    "suppressIfAutoRenew": false,
    "channelIds": [
      "cmuv7k2ab0003xk96channel"
    ],
    "createdAt": "2026-10-05T08:10:00.000Z",
    "updatedAt": "2026-10-05T08:10:00.000Z"
  }
]

Add a rule to a certificate

POST/certificates/:id/rules

Adds an expiry rule to a tracked certificate. Returns 409 with reason rules_not_custom unless the item's rule mode is CUSTOM. 400 once the certificate has 50 rules. suppressIfAutoRenew is accepted but has no effect: uploaded certificates don't renew themselves.

API key scope: rules:write

Path parameters

idstringrequired
The certificate's id

Body parameters

typeenumrequired
CERT_EXPIRY.
thresholdinteger
Required for TLS_EXPIRY, CERT_EXPIRY and DOMAIN_EXPIRY: days before expiry that the rule fires, 0–3650. Required for HTTP_SLOW: the response time in milliseconds it must exceed, 100–9000. Leave null on other types.
severityenum
INFO, WARNING or CRITICAL. Default WARNING. INFO alerts notify but never mark a domain unhealthy, and channels set to critical only skip them; webhooks receive the same three values.
enabledboolean
Default true.
channelIdsstring[]
Channels to notify, up to 20. Leave out for the organization's default channels.
curl -X POST https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"CERT_EXPIRY","threshold":30}'
Response 201
{
  "id": "cmuv7k2ab0002xk96rule001",
  "domainId": null,
  "trackedCertificateId": "cmuv7k2ab0007xk96tracked",
  "type": "CERT_EXPIRY",
  "threshold": 30,
  "severity": "WARNING",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z"
}

Get a rule

GET/rules/:id

One rule, on a domain or a tracked certificate.

API key scope: rules:read

Path parameters

idstringrequired
The rule's id
curl https://certimonitor.com/api/v1/rules/cmuv7k2ab0002xk96rule001 \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
{
  "id": "cmuv7k2ab0002xk96rule001",
  "domainId": "cmuv7k2ab0001xk96example",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 14,
  "severity": "CRITICAL",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z"
}

Update a rule

PATCH/rules/:id

Change any field. channelIds replaces the list; an empty list notifies no one. Returns 409 with reason rules_not_custom unless the item's rule mode is CUSTOM.

API key scope: rules:write

Path parameters

idstringrequired
The rule's id

Body parameters

typeenum
Must be valid for the rule's target.
thresholdinteger
Required for TLS_EXPIRY, CERT_EXPIRY and DOMAIN_EXPIRY: days before expiry that the rule fires, 0–3650. Required for HTTP_SLOW: the response time in milliseconds it must exceed, 100–9000. Leave null on other types.
severityenum
INFO, WARNING or CRITICAL. Default WARNING. INFO alerts notify but never mark a domain unhealthy, and channels set to critical only skip them; webhooks receive the same three values.
enabledboolean
Default true.
suppressIfAutoRenewboolean
TLS_EXPIRY only (ignored on other types): hold the alert while renewal isn't due yet, for certificates CertiMonitor has seen renew automatically before. It still fires once renewal is overdue.
channelIdsstring[]
Channels to notify, up to 20. Leave out for the organization's default channels.
curl -X PATCH https://certimonitor.com/api/v1/rules/cmuv7k2ab0002xk96rule001 \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold":21,"channelIds":["cmuv7k2ab0003xk96channel"]}'
Response 200
{
  "id": "cmuv7k2ab0002xk96rule001",
  "domainId": "cmuv7k2ab0001xk96example",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 21,
  "severity": "CRITICAL",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z"
}

Delete a rule

DELETE/rules/:id

Deletes the rule. Its open alerts close without an all-clear; past alerts stay in the history. Returns 409 with reason rules_not_custom unless the item's rule mode is CUSTOM.

API key scope: rules:write

Path parameters

idstringrequired
The rule's id
curl -X DELETE https://certimonitor.com/api/v1/rules/cmuv7k2ab0002xk96rule001 \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Test a rule

POST/rules/:id/test

Whether the rule would fire on the latest checked data (no new check is run), and which channels would get it. With send: true it also delivers a sample marked as a test, up to 5 a minute.

API key scope: rules:write

Path parameters

idstringrequired
The rule's id

Body parameters

sendboolean
Also send a sample through the rule's channels
curl -X POST https://certimonitor.com/api/v1/rules/cmuv7k2ab0002xk96rule001/test \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"send":false}'
Response 200
{
  "verdict": {
    "state": "fires",
    "severity": "CRITICAL",
    "reason": "TLS certificate expires in 5 days"
  },
  "subject": "example.com",
  "checkedAt": "2026-10-12T09:00:00.000Z",
  "channels": [
    {
      "id": "cmuv7k2ab0003xk96channel",
      "name": "Ops Slack",
      "type": "SLACK",
      "receives": true
    }
  ],
  "sent": null
}

Set a domain's rule mode

PUT/domains/:id/rule-mode

DEFAULT or TAG replace the domain's rules with that source's; CUSTOM keeps the current rules as its own. TAG needs one of the domain's tags that has domain rules.

API key scope: rules:write

Path parameters

idstringrequired
The domain's id

Body parameters

modeenumrequired
DEFAULT, TAG or CUSTOM
tagIdstring
Required with TAG: one of the domain's tags
curl -X PUT https://certimonitor.com/api/v1/domains/cmuv7k2ab0001xk96example/rule-mode \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"TAG","tagId":"cmuv7k2ab0006xk96tag0001"}'
Response
204 No Content

Set a certificate's rule mode

PUT/certificates/:id/rule-mode

The same as for domains: DEFAULT or TAG replace the certificate's rules with that source's; CUSTOM keeps the current rules as its own. TAG needs one of the certificate's tags that has a CERT_EXPIRY rule.

API key scope: rules:write

Path parameters

idstringrequired
The certificate's id

Body parameters

modeenumrequired
DEFAULT, TAG or CUSTOM
tagIdstring
Required with TAG: one of the certificate's tags
curl -X PUT https://certimonitor.com/api/v1/certificates/cmuv7k2ab0007xk96tracked/rule-mode \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"DEFAULT"}'
Response
204 No Content

Tag rules

Rules on a tag, shared by every domain and certificate whose rule mode is TAG with that tag. Changes apply to all of them at once. Domain rule types apply to tagged domains, CERT_EXPIRY to tagged certificates. An item left with no fitting rules falls back to DEFAULT. A tag can have up to 25 rules, and only one of each type and threshold.

List a tag's rules

GET/tags/:id/rules

The rules shared by everything following this tag.

API key scope: rules:read

Path parameters

idstringrequired
The tag's id
curl https://certimonitor.com/api/v1/tags/cmuv7k2ab0006xk96tag0001/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0002xk96rule001",
    "trackedCertificateId": null,
    "type": "TLS_EXPIRY",
    "threshold": 14,
    "severity": "CRITICAL",
    "enabled": true,
    "suppressIfAutoRenew": false,
    "channelIds": [
      "cmuv7k2ab0003xk96channel"
    ],
    "createdAt": "2026-10-05T08:10:00.000Z",
    "updatedAt": "2026-10-05T08:10:00.000Z",
    "tagId": "cmuv7k2ab0006xk96tag0001"
  }
]

Add a rule to a tag

POST/tags/:id/rules

Added at once to every domain or certificate following the tag. 409 if the tag already has a rule with the same type and threshold; 400 once it has 25 rules.

API key scope: rules:write

Path parameters

idstringrequired
The tag's id

Body parameters

typeenumrequired
Any domain or certificate rule type.
thresholdinteger
Required for TLS_EXPIRY, CERT_EXPIRY and DOMAIN_EXPIRY: days before expiry that the rule fires, 0–3650. Required for HTTP_SLOW: the response time in milliseconds it must exceed, 100–9000. Leave null on other types.
severityenum
INFO, WARNING or CRITICAL. Default WARNING. INFO alerts notify but never mark a domain unhealthy, and channels set to critical only skip them; webhooks receive the same three values.
enabledboolean
Default true.
suppressIfAutoRenewboolean
TLS_EXPIRY only (ignored on other types): hold the alert while renewal isn't due yet, for certificates CertiMonitor has seen renew automatically before. It still fires once renewal is overdue.
channelIdsstring[]
Channels to notify, up to 20. Leave out for the organization's default channels.
curl -X POST https://certimonitor.com/api/v1/tags/cmuv7k2ab0006xk96tag0001/rules \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"TLS_EXPIRY","threshold":14,"severity":"CRITICAL","channelIds":["cmuv7k2ab0003xk96channel"]}'
Response 201
{
  "id": "cmuv7k2ab0002xk96rule001",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 14,
  "severity": "CRITICAL",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z",
  "tagId": "cmuv7k2ab0006xk96tag0001"
}

Get a tag rule

GET/tag-rules/:id

One tag rule, with its channels and tag.

API key scope: rules:read

Path parameters

idstringrequired
The tag rule's id
curl https://certimonitor.com/api/v1/tag-rules/ID \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
{
  "id": "cmuv7k2ab0002xk96rule001",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 14,
  "severity": "CRITICAL",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z",
  "tagId": "cmuv7k2ab0006xk96tag0001",
  "tag": {
    "id": "cmuv7k2ab0006xk96tag0001",
    "name": "Production",
    "slug": "production",
    "color": "GREEN",
    "createdAt": "2026-10-05T08:30:00.000Z"
  }
}

Update a tag rule

PATCH/tag-rules/:id

Updates its copy on every follower. Open alerts carry on when only severity or channels change. 409 if the new type and threshold match another of the tag's rules.

API key scope: rules:write

Path parameters

idstringrequired
The tag rule's id

Body parameters

typeenum
Any domain or certificate rule type.
thresholdinteger
Required for TLS_EXPIRY, CERT_EXPIRY and DOMAIN_EXPIRY: days before expiry that the rule fires, 0–3650. Required for HTTP_SLOW: the response time in milliseconds it must exceed, 100–9000. Leave null on other types.
severityenum
INFO, WARNING or CRITICAL. Default WARNING. INFO alerts notify but never mark a domain unhealthy, and channels set to critical only skip them; webhooks receive the same three values.
enabledboolean
Default true.
suppressIfAutoRenewboolean
TLS_EXPIRY only (ignored on other types): hold the alert while renewal isn't due yet, for certificates CertiMonitor has seen renew automatically before. It still fires once renewal is overdue.
channelIdsstring[]
Channels to notify, up to 20. Leave out for the organization's default channels.
curl -X PATCH https://certimonitor.com/api/v1/tag-rules/ID \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"severity":"WARNING"}'
Response 200
{
  "id": "cmuv7k2ab0002xk96rule001",
  "trackedCertificateId": null,
  "type": "TLS_EXPIRY",
  "threshold": 14,
  "severity": "WARNING",
  "enabled": true,
  "suppressIfAutoRenew": false,
  "channelIds": [
    "cmuv7k2ab0003xk96channel"
  ],
  "createdAt": "2026-10-05T08:10:00.000Z",
  "updatedAt": "2026-10-05T08:10:00.000Z",
  "tagId": "cmuv7k2ab0006xk96tag0001"
}

Delete a tag rule

DELETE/tag-rules/:id

Removes it from every follower. Their open alerts close without an all-clear; past alerts stay in the history.

API key scope: rules:write

Path parameters

idstringrequired
The tag rule's id
curl -X DELETE https://certimonitor.com/api/v1/tag-rules/ID \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Test a tag rule

POST/tag-rules/:id/test

How many followers it would fire for now, with up to 5 examples. send: true sends a sample.

API key scope: rules:write

Path parameters

idstringrequired
The tag rule's id

Body parameters

sendboolean
Also send a sample through the rule's channels
curl -X POST https://certimonitor.com/api/v1/tag-rules/ID/test \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"send":false}'
Response 200
{
  "followers": 12,
  "firing": 1,
  "examples": [],
  "channels": [
    {
      "id": "cmuv7k2ab0003xk96channel",
      "name": "Ops Slack",
      "type": "SLACK",
      "receives": true
    }
  ],
  "sent": null
}

Channels

Where alerts go: email, Slack, Discord, Microsoft Teams or your own webhook. Destinations are encrypted at rest and never returned in full; responses describe them instead.

List channels

GET/channels

Every channel with its delivery status and how many rules use it.

API key scope: channels:read

curl https://certimonitor.com/api/v1/channels \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0003xk96channel",
    "name": "Ops alerts",
    "type": "SLACK",
    "enabled": true,
    "isDefault": true,
    "sendResolved": true,
    "criticalOnly": false,
    "mentionOnCritical": true,
    "destination": "hooks.slack.com/…/T0001",
    "lastDeliveredAt": "2026-10-01T09:12:44.000Z",
    "lastFailedAt": null,
    "lastError": null,
    "confirmedAt": null,
    "unsubscribedAt": null,
    "createdAt": "2026-09-06T08:05:00.000Z",
    "updatedAt": "2026-09-06T08:05:00.000Z",
    "rules": 12,
    "consent": null
  }
]

Add a channel

POST/channels

Creates a channel. For a WEBHOOK, the response includes signingSecret once; store it to verify deliveries. An EMAIL channel to anyone but a verified member of the organization starts with consent "pending": the address gets a confirmation email and no alerts until its owner confirms. Every alert email has a one-click unsubscribe, after which consent is "unsubscribed". Confirmation emails are limited to 10 an hour per organization and 3 an hour per address (429).

API key scope: channels:write

Body parameters

typeenumrequired
EMAIL, SLACK, DISCORD, TEAMS or WEBHOOK.
namestringrequired
Display name, up to 64 characters.
targetstringrequired
An email address, or the https URL of the incoming webhook.
isDefaultboolean
Attach this channel to the rules of new domains and certificates.
sendResolvedboolean
Also send a message when an alert resolves.
criticalOnlyboolean
Only send CRITICAL alerts.
mentionOnCriticalboolean
Slack: add @here to CRITICAL alerts.
curl -X POST https://certimonitor.com/api/v1/channels \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"WEBHOOK","name":"Incident bot","target":"https://hooks.example.com/certimonitor"}'
Response 201
{
  "id": "cmuv7k2ab0003xk96channel",
  "name": "Incident bot",
  "type": "WEBHOOK",
  "enabled": true,
  "isDefault": false,
  "sendResolved": true,
  "criticalOnly": false,
  "mentionOnCritical": false,
  "destination": "hooks.example.com/…",
  "lastDeliveredAt": null,
  "lastFailedAt": null,
  "lastError": null,
  "confirmedAt": null,
  "unsubscribedAt": null,
  "createdAt": "2026-09-06T08:05:00.000Z",
  "updatedAt": "2026-09-06T08:05:00.000Z",
  "rules": 0,
  "consent": null,
  "signingSecret": "whsec_3QeT…"
}

Update a channel

PATCH/channels/:id

Change its name, destination or options, pause it, or rotate a webhook's signing secret.

API key scope: channels:write

Path parameters

idstringrequired
The channel's id

Body parameters

namestring
Display name, up to 64 characters.
targetstring
New email address or webhook URL.
enabledboolean
false stops deliveries to this channel.
isDefaultboolean
Attach this channel to the rules of new domains and certificates.
sendResolvedboolean
Also send a message when an alert resolves.
criticalOnlyboolean
Only send CRITICAL alerts.
mentionOnCriticalboolean
Slack: add @here to CRITICAL alerts.
rotateSecrettrue
WEBHOOK only: issue a new signing secret, returned once in this response.
curl -X PATCH https://certimonitor.com/api/v1/channels/cmuv7k2ab0003xk96channel \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"criticalOnly":true}'
Response 200
{
  "id": "cmuv7k2ab0003xk96channel",
  "name": "Ops alerts",
  "type": "SLACK",
  "enabled": true,
  "isDefault": true,
  "sendResolved": true,
  "criticalOnly": true,
  "mentionOnCritical": true,
  "destination": "hooks.slack.com/…/T0001",
  "lastDeliveredAt": "2026-10-01T09:12:44.000Z",
  "lastFailedAt": null,
  "lastError": null,
  "confirmedAt": null,
  "unsubscribedAt": null,
  "createdAt": "2026-09-06T08:05:00.000Z",
  "updatedAt": "2026-09-06T08:05:00.000Z",
  "rules": 12,
  "consent": null
}

Delete a channel

DELETE/channels/:id

Deletes the channel and unlinks it from every rule.

API key scope: channels:write

Path parameters

idstringrequired
The channel's id
curl -X DELETE https://certimonitor.com/api/v1/channels/cmuv7k2ab0003xk96channel \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Test a destination

POST/channels/test

Sends a test message to a destination before you save it. Limited to 5 test sends a minute per organization (shared with Test a channel), 20 unsaved destinations an hour, and 3 tests an hour to the same destination. An email address can only be tested this way if it's a verified member's own; any other address is confirmed by its owner after you save the channel.

API key scope: channels:write

Body parameters

typeenumrequired
EMAIL, SLACK, DISCORD, TEAMS or WEBHOOK.
targetstringrequired
The email address or webhook URL to test.
curl -X POST https://certimonitor.com/api/v1/channels/test \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"SLACK","target":"https://hooks.slack.com/services/T000/B000/XXXX"}'
Response
204 No Content

Test a channel

POST/channels/:id/test

Sends a test message to a saved channel (204). Limited to 5 test sends a minute per organization and 3 an hour to the same destination. An email channel that is waiting for confirmation, or whose recipient unsubscribed, gets the confirmation email again instead (202), limited to 10 an hour per organization and 3 an hour per address.

API key scope: channels:write

Path parameters

idstringrequired
The channel's id
curl -X POST https://certimonitor.com/api/v1/channels/cmuv7k2ab0003xk96channel/test \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Tags

Labels for organizing domains and certificates. Items are tagged by name, so setting tags on a domain or certificate creates any that don't exist yet; domains:write or certificates:write is enough for that.

List tags

GET/tags

Every tag, with how many domains and certificates use it.

API key scope: tags:read

curl https://certimonitor.com/api/v1/tags \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response 200
[
  {
    "id": "cmuv7k2ab0006xk96tag0001",
    "name": "Production",
    "slug": "production",
    "color": "GREEN",
    "createdAt": "2026-10-05T08:30:00.000Z",
    "_count": {
      "domains": 4,
      "trackedCertificates": 1
    }
  }
]

Create a tag

POST/tags

Creates a tag.

API key scope: tags:write

Body parameters

namestringrequired
Up to 32 characters, with at least one letter or number.
colorenum
GRAY, RED, AMBER, GREEN, BLUE or PURPLE.
curl -X POST https://certimonitor.com/api/v1/tags \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","color":"GREEN"}'
Response 201
{
  "id": "cmuv7k2ab0006xk96tag0001",
  "name": "Production",
  "slug": "production",
  "color": "GREEN",
  "createdAt": "2026-10-05T08:30:00.000Z"
}

Update a tag

PATCH/tags/:id

Rename or recolor a tag.

API key scope: tags:write

Path parameters

idstringrequired
The tag's id

Body parameters

namestring
Up to 32 characters.
colorenum
GRAY, RED, AMBER, GREEN, BLUE or PURPLE.
curl -X PATCH https://certimonitor.com/api/v1/tags/cmuv7k2ab0006xk96tag0001 \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"BLUE"}'
Response 200
{
  "id": "cmuv7k2ab0006xk96tag0001",
  "name": "Production",
  "slug": "production",
  "color": "BLUE",
  "createdAt": "2026-10-05T08:30:00.000Z"
}

Delete a tag

DELETE/tags/:id

Deletes the tag and removes it from every item.

API key scope: tags:write

Path parameters

idstringrequired
The tag's id
curl -X DELETE https://certimonitor.com/api/v1/tags/cmuv7k2ab0006xk96tag0001 \
  -H "Authorization: Bearer $CERTIMONITOR_API_KEY"
Response
204 No Content

Webhooks

A WEBHOOK channel POSTs JSON to your URL when an alert opens or resolves, and when you send a test. Respond with any 2xx status. Failed deliveries are retried on later runs for up to 24 hours, so the same event can arrive more than once: deduplicate on id and type.

X-CertiMonitor-Event
alert.opened, alert.resolved or alert.test
X-CertiMonitor-Delivery
Unique per event and kind, for deduplication
X-CertiMonitor-Signature
t=<unix seconds>,v1=<hex HMAC-SHA256>

Verifying signatures

Every request is signed with the channel's signing secret, returned once when you create the channel or rotate the secret. Compute an HMAC-SHA256 of {t}.{raw body} with the secret and compare it to v1. Reject timestamps more than a few minutes old to block replays.

Payload
{
  "id": "cmuv7k2ab0009xk96event01",
  "type": "alert.opened",
  "createdAt": "2026-10-05T08:00:09.000Z",
  "alert": {
    "subject": "example.com",
    "headline": "Certificate expires in 6 days",
    "severity": "CRITICAL",
    "alertType": "TLS_EXPIRY",
    "advice": "Renew the certificate, or check that automatic renewal is working.",
    "details": [
      {
        "label": "Expires",
        "value": "11 Oct 2026, 22:29"
      },
      {
        "label": "Issuer",
        "value": "Let's Encrypt (R11)"
      }
    ],
    "openedAt": "2026-10-05T08:00:07.000Z",
    "resolvedAt": null,
    "url": "https://certimonitor.com/domains/cmuv7k2ab0001xk96example",
    "organization": "Acme"
  }
}
import { createHmac, timingSafeEqual } from "node:crypto"

// rawBody: the request body exactly as received, before JSON parsing
export function verifyCertiMonitor(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")))
  const timestamp = Number(parts.t)
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")
  const received = Buffer.from(parts.v1 ?? "")
  return received.length === expected.length && timingSafeEqual(Buffer.from(expected), received)
}