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:

MethodPathWhat it does
GET/v1/endpointsList 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/endpointsAdd 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}/checkCheck 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}/acknowledgeAcknowledge the open alert. No body.
DELETE/v1/endpoints/{id}/acknowledgeWithdraw the acknowledgement. No body.
GET/v1/endpoints/{id}/checksCheck 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/domainsList 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/domainsAdd one — {name}, a registrable domain like example.com.
POST/v1/domains/{id}/checkCheck now for a domain, as for an endpoint.
GET/v1/domains/{id}/checksCheck history, most recent first, each check with kind and reason as for an endpoint's.
POST/v1/domains/checkLook 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/accountPlan, 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/accountUpdate 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:

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.

MethodPathWhat it does
GET/v1/alert-channels/readinessEach 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/summaryAlerts 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}/retryResend 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:

typeSent for
lateA Late alert (see alert types).
urgentAn Urgent alert.
downA Down alert.
unreachableAn Unreachable alert.
recoveredA 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.
testA test from the Alerting page: id, type, schema_version, occurred_at, test: true, and summary, with no monitor or condition.
delivery_failureA Delivery notice that another of your alert channels is failing. No monitor or condition.
delivery_recoveredA 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:

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.