API
CertWatch's app is a client of its own /v1 HTTP/JSON API. There's no separate public
API key today — authenticated routes use the same session cookie the app sets on login, and one
route (the certificate checker) is intentionally open with no account required.
Authentication
POST /v1/login and POST /v1/signup set an HttpOnly,
SameSite=Lax session cookie good for 30 days from creation (not a sliding window).
POST /v1/logout clears it and works even against an already-expired or missing cookie.
Forgotten-password flows (/v1/password-reset/request, /v1/password-reset/confirm)
don't require a session, for the obvious reason, and never reveal whether a given email has an account.
POST /v1/account/password changes the password of the signed-in user; it keeps the session
that made the change and ends every other one.
Endpoints and domains
Session-gated. The shapes mirror what the app shows:
| Method | Path | What it does |
|---|---|---|
| GET | /v1/endpoints | List TLS endpoints, newest first. Each carries latest_attempt, its last check: id, completed_at (with fractional seconds when it has them), kind (scheduled, on_demand for a check a person or the API asked for, or follow_up for the check that confirms a finding), outcome, and reason. days_remaining and last_checked_at are deprecated and always null. |
| POST | /v1/endpoints | Add one — {hostname, port, label, renewal_mode?, renewal_days_left?}, port defaults to 443. Without a renewal mode it starts in auto. |
| PATCH | /v1/endpoints/{id} | Partial update — label, active state, mute, or renewal mode (renewal_mode, renewal_days_left). The hostname and port can't be changed: a request naming hostname or port is 400 invalid_request and saves nothing. |
| DELETE | /v1/endpoints/{id} | Remove one. |
| POST | /v1/endpoints/{id}/check | Check now. No body. Returns 202 with the endpoint as it stood and check_id, the id of the check it started. Once that check is saved and is the last one, a read's latest_attempt.id is the check_id. That may never happen: a check that could not be saved leaves no result, and a newer check can finish first. Stop polling after a while; the app stops after 30 seconds. |
| POST | /v1/endpoints/{id}/acknowledge | Acknowledge the open alert. No body. |
| DELETE | /v1/endpoints/{id}/acknowledge | Withdraw the acknowledgement. No body. |
| GET | /v1/endpoints/{id}/checks | Check history, most recent first. Each check's kind is as in latest_attempt, and reason says why an on_demand or follow_up check ran: check_now, added, resumed, renewal_changed, or confirmation; it is absent when the check stored none. A check that read a certificate gives its issuer's common name as issuer and, when known, its organization as issuer_org. Each check's addresses lists the addresses it recorded (the hostname's first eight), ordered by IP, as {ip, outcome}: served, failed, skipped (an internal address CertWatch will not dial), or not_probed (not tried: no IPv6 route, or the check ran out of time). A served address also gives the certificate it served, as three more fields: its SHA-256 fingerprint, its not_after, and its verify_outcome, which is ok, expired, not_yet_valid, hostname_mismatch, self_signed, untrusted_root, unknown_authority, incomplete_chain, or insecure_signature. Each is absent when CertWatch holds none, such as the not_after of an expired certificate on an older check, which CertWatch deletes once it has seen several newer ones. expired also covers an expired intermediate certificate under a leaf that has not expired. On a check CertWatch could not finish on its own side (certwatch_timeout), the verify_outcome is what it read before it ran out of time, not a verdict on your host. |
| GET | /v1/domains | List monitored domains, each with latest_attempt as for an endpoint, except that a domain check's kind is never follow_up. last_checked_at is deprecated and always null. |
| POST | /v1/domains | Add one — {name}, a registrable domain like example.com. |
| POST | /v1/domains/{id}/check | Check now for a domain, as for an endpoint. |
| GET | /v1/domains/{id}/checks | Check history, most recent first, each check with kind and reason as for an endpoint's. |
| POST | /v1/domains/check | Look a domain up without adding it — {name}. Returns {supported, registrar, expires_at, expiry_missing}, or 502 domain_lookup_failed when the registry gives no answer about it. |
| GET | /v1/account | Plan, limits, current usage, slack_connection ({workspace_name, channel_id, channel_name}, or null), and channel_policy: each severity (late, urgent, down, unreachable) by each channel (email, slack, webhook), true where that severity's alerts go (see Alert channels). |
| PATCH | /v1/account | Update the alert email, the webhook URL (Pro), the Slack mention (<!here>, <!channel>, or empty for none), channel_policy, or display name. A channel_policy replaces only the cells it names, so {"late": {"slack": false}} changes one; anything else is 400 invalid_channel_policy. |
Each domain also carries registry_statuses, its registry status codes such as
client transfer prohibited or redemption period, and rdap_source, the
RDAP server that answered (rdap.verisign.com), from the last check in which the registry
answered. rdap_source is null until a registry has answered for the domain, and
registry_statuses is null until an answer has listed statuses: a registry that
answers without them leaves it null, or as its last list.
Each domain also carries late_at and urgent_at, the times its registration turns
Late and Urgent: 30 days and 7 days before expires_at. Both are null until the
domain has an expiry date.
Each domain also carries last_alert, {id, severity, created_at} of the newest alert
sent about its current problem: a Late, Urgent or Down alert about its registration, or the Unreachable alert
sent after 24 hours of failed lookups. severity is late, urgent,
down or unreachable. It is null while the domain is Healthy, when no
alert has been sent about the current problem, and once that alert is older than 90 days, the time Alert
history keeps it.
Every endpoint and domain also carries triggered, whether it is
Triggered, with triggered_group (down,
urgent, unreachable, or late) when it is, and paused_at, when
you paused it or a plan change paused it. paused_at is null while the monitor is
active, and on a monitor paused so long ago that CertWatch has no date for the pause. A paused monitor has
no status: its status, reason and freshness are null,
timeliness is paused, triggered is false, and it carries
no latest_attempt or last_known. As for a monitor not yet checked, an endpoint's
not_after and renewal dates are null and a domain's expires_at is
left out, until the check its resume starts.
Adding an endpoint or domain past your plan's limit returns 403 endpoint_limit_reached /
403 domain_limit_reached; a duplicate returns 409, including the same name with a
trailing dot (example.com. is saved as example.com). Every mutating route
is scoped strictly to the caller's own account — another account's monitor id 404s rather than 403ing, so
a guessed id can't be used to confirm it exists.
Check now returns 409 monitor_paused for a paused monitor, 409 check_in_progress
while a check of it is already running, 503 check_unavailable while CertWatch is restarting (try
again shortly), and 404 for a monitor that is not yours. It and the domain lookup share a limit of
10 requests a minute per account (429 rate_limited). A Check now moves no schedule. When an
endpoint's Check now finds a status you have not been sent, its alert goes at once; reminders come only with
scheduled checks, and a domain's alerts with its next scheduled check. Saving a new renewal mode or day count on an active endpoint checks it
the same way, without counting against the limit.
Endpoint fields
Besides its hostname, port, label, and status, each endpoint the list and PATCH return carries:
-
renewal_mode:auto,manual, ordeclared("renews with a set number of days left", see Renewal mode), andrenewal_days_left, the days left when it renews (1 to 397,nullunlessdeclared). Any other mode is400 invalid_renewal_mode, andrenewal_days_leftis required withdeclaredand refused otherwise (400 invalid_renewal_days_left). OnPATCH, a day count as long as the current certificate's lifetime or longer is422 renewal_days_left_exceeds_lifetime, and nothing is saved; before the endpoint's first check, it saves, and each check sets it aside instead.renewal_mode_sourceisdefaultuntil you choose a mode, thencustomer, withrenewal_mode_set_at.renewal_mode_suggestionis deprecated and alwaysnull; it will be removed. -
rescue_suggestion:{"renewal_mode": "declared", "renewal_days_left": N}when the endpoint is automatic and the only renewal CertWatch has seen came so close to expiry that it was not learned (see When a certificate is Late or Urgent), N being that renewal's days left, rounded up, at least 1; elsenull. Send it toPATCHas it is to declare that schedule. -
unreachable_alert_due_at: alwaysnull. An endpoint is Unreachable once a second failed check confirms the first, normally the follow-up check about two minutes later, so there is no later time to give; until thenstatusstays the last reading's (an endpoint never read is Unreachable at once). -
late_atandurgent_at: when the certificate turns Late and Urgent (equal only when both are at the expiry),basis, the evidence they come from (manual,declared,ari,history, ordefault), andlearning,trueon the default.conditionslists the last check's findings, worst first, as{code, state?, addresses?, since?, confirmation?}: a finding without astatenever changes the status, and one whoseconfirmationispendingdoes not count yet (a failed check'sprobe-failedcounts at once only on an endpoint never read). These five arenulluntil the current hostname and port have been checked, and all butconditionsare alsonullwhen the certificate's start date is unknown. They all come from the endpoint's last check, so aPATCHthat changes the renewal mode returns the last check's. They move when a check saved under the new setting lands: the one thePATCHstarts on an active endpoint, or one already running, which starts no second. A paused endpoint has none of them until the check its resume starts.ari_windowis the CA's latest renewal window for the certificate,{start, end, fetched_at}, ornull. -
renewal_certificate: the certificatelate_atandurgent_atare measured on,{not_before, not_after, effective_not_after}. It is the newest certificate served at the last check, passing over a broken one (such as a default certificate) when a working one is served beside it;effective_not_afteris the date the points count back from, earlier thannot_afterwhen an intermediate expires first, andnot_beforeisnullwhen unknown.renewal_optionsis{automatic: {basis, late_at, urgent_at, from_window_start}}, the dates that certificate gets in automatic mode, the same as the top-level ones when the endpoint is automatic, so you can show what switching back to automatic would give.from_window_startistruewhenlate_atis the CA's recommended renewal start, because the learned date came before it. Both arenulluntil the current hostname and port have been checked;renewal_certificateis alsonullwhen no certificate has been seen, andautomaticisnullwhen the certificate's start date is unknown. -
open_alert:{severity, acknowledgement, alert_id, opened_at, first_sent_at, last_sent_at, next_alert}for the endpoint's open alert once it has been sent, elsenull;acknowledgementis{acknowledged_at, acknowledged_by}while one holds, which is until the alert ends; a click in Slack reads"Sam (Slack)".alert_idis the alert's newest message in Alert history,nullonce all its messages are older than the 90 days Alert history keeps;opened_atis when the alert opened, andfirst_sent_atandlast_sent_atwhen its first and last messages went out.next_alertis{at, kind, severity, cause, held_by, held_until}, the next message the alert sends if nothing changes:kindisannouncement,reminderorreachable_again,causean announcement'sclock,findingorreach, andheld_by(acknowledgeormute) the hold keeping back the message that would otherwise go, untilheld_until(nullfor an acknowledgement, which ends with the alert).next_alertis the message that will actually go, so an acknowledged Late or Urgent alert's is its next announcement, andnullwhen no message is coming, as on an acknowledged Down whose expiry was sent.
The acknowledge routes return the endpoint. Acknowledging takes no body (a
severity sent is ignored) and answers 409 nothing_to_acknowledge when no alert is
open or none has been sent; acknowledging again records another event. Withdrawing ends the acknowledgement,
recorded as acknowledgement_withdrawn, and with none answers
200 unchanged, recording nothing. See
Acknowledge for what it holds.
Alert delivery
Session-gated. "Accepted" means your email provider, Slack, or webhook took the alert, not that someone read it.
| Method | Path | What it does |
|---|---|---|
| GET | /v1/alert-channels/readiness | Each channel's setup and acceptance evidence. last_test is {at, outcome, problem_code} for the channel's current destination, null until you send a test: outcome is accepted or failed, with a fixed problem_code when it failed. A test email that later bounces, is marked as spam, or is suppressed turns it failed. |
| GET | /v1/alerts/summary | Alerts since ?since= (RFC 3339, up to 90 days back; default the last 24 hours): alerts_by_severity gives {total, delivered} for late, urgent, unreachable and down, delivered meaning at least one channel accepted the alert, and by_channel counts each channel's deliveries accepted, failed, and retrying. 400 invalid_since for anything else. |
| POST | /v1/alerts/delivery-problems/{channel}/retry | Resend every failed alert on email, slack, or webhook to its current destination. Returns {retried, skipped} straight away (skipped ones were already being sent or are waiting for an automatic retry) and sends in the background, spaced out so the receiver doesn't refuse them. 409 channel_not_usable with a problem_code (channel_unconfigured, channel_not_entitled, email_unverified) when the channel can't receive alerts; nothing is resent. 429 rate_limited when you retry too often. |
Public certificate check
POST /v1/check — {host} (a hostname[:port] string, port defaults to
443). No authentication, nothing persisted: runs one TLS check and returns the result plus a computed
status (healthy / late / urgent / down /
unreachable). With no history for the certificate, it reads the certificate as CertWatch reads a
new endpoint's before any renewal has been seen, so a monitored endpoint with renewal evidence can show a
different status. A server that doesn't send its intermediate certificate reads urgent, with
chain_valid false, when the check can fetch the intermediate from the address the certificate
names; any other chain that doesn't validate reads down. days_remaining counts
whole days left to the certificate's expiry, rounded down: 0 with under a day left, -1 from just after it
expires. Every check that reads a certificate, an expired or down one included, also returns
three timestamps in RFC 3339 UTC: not_before, when the certificate was issued;
effective_not_after, the earliest expiry in the chain the check judged (of the paths that
verify, the one that stays valid longest; the certificates the server sends when none verifies), which is
the certificate's own unless an intermediate on that chain expires first; and urgent_at, 7 days or a twentieth of
the certificate's lifetime before effective_not_after, whichever is shorter, from which a
certificate with a valid chain reads urgent. urgent_at is left out when the
certificate's start is not before its expiry. A check that reads no certificate (unreachable)
returns none of them. Rate-limited per client IP (429 rate_limited, with Retry-After)
since it requires no account to attribute requests to.
Webhook payload
A generic webhook (Pro) receives each message as one signed JSON object: id (stable across
retries, so dedupe on it), type, schema_version (3),
occurred_at, test, monitor, summary (the alert's text;
don't parse it), and condition, the finding behind the alert. A retry sends the same id again.
type is one of eight values:
type | Sent for |
|---|---|
late | A Late alert (see alert types). |
urgent | An Urgent alert. |
down | A Down alert. |
unreachable | An Unreachable alert. |
recovered | A Recovered alert. It does not say which alert it ends: pair it with an earlier alert by monitor.id and time, or read the monitor's History. |
test | A test from the Alerting page: id, type, schema_version, occurred_at, test: true, and summary, with no monitor or condition. |
delivery_failure | A Delivery notice that another of your alert channels is failing. No monitor or condition. |
delivery_recovered | A Delivery notice that that channel is accepting alerts again. No monitor or condition. |
monitor is {type, id, label} plus hostname and port for an
endpoint or domain for a domain. The condition object's fields:
-
kind: the finding, lowercase and hyphenated. For an endpoint it is the worst finding at the alert's severity, such asrenewal-overdue,renewal-very-overdue,partial-rollout,ca-recall,chain-incomplete,intermediate-expires-first,weak-key,sha1-signature,lifetime-over-398d,expired,not-yet-valid,hostname-mismatch,untrusted-root,self-signed,unknown-authority,probe-failed, ornot-probed, anddays-remainingwhen no recorded finding is at that severity; thesummarywords the rest. For a domain it isdomain-days-remaining,domain-expired, ordomain-lookup-failed, and for a Recovered it isrecovered. -
severity:late,urgent,down, orunreachable; on a Recovered, the severity of what ended. Read the alert's level from this or fromtype, not from a day count. Absent on a domain's Unreachable alert and its Recovered. -
threshold_days: for a certificate, the days left before expiry at its Late point on alatealert or at its Urgent point on anurgentone, in whole days and never0, a point set by when the endpoint is expected to renew (see when a certificate is Late or Urgent). For a domain registration it is 30 on alatealert and 7 on anurgentone, whatever the days left. It is0once the certificate or registration has expired. Absent on anunreachableorrecoveredalert, on a Down alert for a certificate clients reject (a name, trust, or validity finding), and on an Urgent alert for a missing intermediate. -
not_after: the certificate's or registration's expiry, when there is one; on a Recovered, the expiry the check that ended it read. Absent on anunreachablealert, and on a Recovered that ends a broken chain or an Unreachable alert. -
late_at,urgent_at, andbasis: the endpoint's renewal dates and their evidence, as on its endpoint fields, measured on the certificate the alert is about. On an endpoint's Late, Urgent, Down, and Unreachable alerts once a certificate has been read; absent on a Recovered, on a domain's alerts, and on an older alert sent before these fields existed. last_seen_at: on an alert about a check that read no certificate, when the certificate last seen was last read.addresses: the addresses the finding was on, when it was on only some of those that served, or forprobe-failedthe addresses that failed. Absent when it was on all of them.
Each request is signed with your account's webhook signing secret: the X-CertWatch-Signature
header is t=<unix-seconds>,v1=<hex-hmac-sha256>, an HMAC-SHA256 keyed by the
secret over the timestamp, a dot, and the exact request body bytes, and
X-CertWatch-Alert-Id and X-CertWatch-Alert-Type repeat id and
type. Get the secret with GET /v1/account/webhook-secret and replace it with
POST /v1/account/webhook-secret/rotate.
Billing
POST /v1/billing/checkout and POST /v1/billing/portal return hosted Stripe
links for upgrading and for managing an existing subscription (plan changes, cancellation, payment
methods) respectively — see Billing for what each plan includes.
Validation and abuse controls
A hostname or domain name is saved and checked with one trailing dot dropped. A name with an empty label,
such as .com or a..b, returns 400 invalid_hostname (endpoints and
POST /v1/check) or 400 invalid_domain (domains). A domain name with ?, #, or
% is 400 invalid_domain too.
Hostnames and webhook URLs are checked against internal/private address ranges both when you save them and again at dial time (so a hostname that later resolves somewhere internal via DNS rebinding still gets caught) — CertWatch never dials loopback, link-local, RFC 1918/IPv6 unique-local, CGNAT, multicast, or unspecified addresses on your behalf.