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
- Create a key under Settings, API keys with the scopes you need, and keep it in your secret store as
CERTIMONITOR_API_KEY. - Add a domain and list what you monitor:
# 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.
| Resource | Read | Write |
|---|---|---|
| Domains | domains:read | domains:write |
| Certificates | certificates:read | certificates:write |
| Alert rules | rules:read | rules:write |
| Channels | channels:read | channels:write |
| Tags | tags:read | tags: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"[
{
"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"]}'{
"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"{
"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"]}'{
"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"204 No ContentImport 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"]}]}'{
"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"]}'{
"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"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"[
{
"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"[
{
"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"{
"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"[
{
"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"[
{
"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"}'{
"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"{
"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-----"}'{
"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"204 No ContentAlert 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"[
{
"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"}'{
"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"[
{
"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}'{
"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"{
"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"]}'{
"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"204 No ContentTest 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}'{
"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"}'204 No ContentSet 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"}'204 No ContentTag 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"[
{
"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"]}'{
"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"{
"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"}'{
"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"204 No ContentTest 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}'{
"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"[
{
"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"}'{
"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}'{
"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"204 No ContentTest 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"}'204 No ContentTest 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"204 No ContentCreate 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"}'{
"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"}'{
"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"204 No ContentWebhooks
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.
{
"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)
}