Everything you can do with monitors in the dashboard, you can do over REST. Base URL: https://www.tracewarrior.com/api/v1. All requests and responses are JSON. Use the www host exactly as shown: the bare domain redirects, and most HTTP clients drop the Authorization header when they follow a redirect to another host.
Authentication
API access is included in the Professional and Enterprise plans. Create a key in Dashboard → Profile → API keys. The full key (starting tw_) is shown once at creation; we store only a hash. Send it on every request:
curl https://www.tracewarrior.com/api/v1/monitors \ -H "Authorization: Bearer tw_your_key_here"
Requests without a valid key get 401. A valid key on a plan without API access gets 402.
Finding a monitor ID
Every monitor has a UUID. You can copy it from the monitor's page in the dashboard (next to the target, under the title), read it from the dashboard URL, or list your monitors with the API below: each monitor object includes its id.
Endpoints
GET /api/v1/monitors
List every monitor on your account.
curl https://www.tracewarrior.com/api/v1/monitors \
-H "Authorization: Bearer tw_your_key_here"
{
"monitors": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "Example SSL watch",
"type": "ssl-expiry",
"target_host": "example.com",
"target_port": 443,
"target_path": null,
"config": { "alertWarningDays": 30, "alertCriticalDays": 7 },
"interval_seconds": 900,
"state": "warning",
"state_since": "2026-06-12T20:00:41.123456+00:00",
"last_check_at": "2026-06-12T20:15:41.123456+00:00",
"next_check_at": "2026-06-12T20:30:41.123456+00:00",
"paused": false,
"email_alerts": true,
"recovery_alerts": true,
"webhook_url": null,
"public_status_page": null,
"created_at": "2026-06-12T19:55:02.123456+00:00",
"updated_at": "2026-06-12T20:00:41.123456+00:00"
}
]
}state is one of pending, ok, warning, critical, error (the check itself failed) or paused.
GET /api/v1/monitors/:id
Fetch one monitor. Returns { "monitor": { … } } with the same shape as above, or 404 if the ID doesn't exist on your account.
POST /api/v1/monitors
Create a monitor. Plan limits apply exactly as in the dashboard (monitor count and minimum interval). Required fields: name (up to 80 characters), type, target_host and interval_seconds. Optional: target_port (1 to 65535, required for ssl-expiry and port-tcp), target_path, config, email_alerts, recovery_alerts and webhook_url.
For most types target_host is a hostname or IP address; a pasted URL is reduced to its hostname. For http-status it can be a full URL such as https://example.com/health, and the scheme, port and path (with query string) are all kept. A bare hostname means https. For ssl-expiry and port-tcp, target_host may also carry a port, such as github.com:8443 or [2606:4700:4700::1111]:53. That port is used when target_port is left out, and must match it when both are sent.
curl -X POST https://www.tracewarrior.com/api/v1/monitors \
-H "Authorization: Bearer tw_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Example SSL watch",
"type": "ssl-expiry",
"target_host": "example.com",
"target_port": 443,
"interval_seconds": 900,
"config": { "alertWarningDays": 30, "alertCriticalDays": 7 },
"email_alerts": true
}'curl -X POST https://www.tracewarrior.com/api/v1/monitors \
-H "Authorization: Bearer tw_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Homepage up",
"type": "http-status",
"target_host": "https://example.com/",
"interval_seconds": 300,
"config": { "expectedStatus": [200] }
}'For webhook alerts, add a webhook_url field with your own endpoint, such as a Slack or Discord incoming webhook URL. It must be a public https:// (or http://) URL whose host resolves in public DNS.
Returns 201 with the created monitor and a webhook_secret field. If you supplied a webhook_url, that secret is shown once only: store it to verify alert signatures (see Webhooks below). Otherwise it is null.
PATCH /api/v1/monitors/:id
Update a monitor. All fields optional: name, target_host, target_port, target_path, interval_seconds, config, email_alerts, recovery_alerts, webhook_url, paused. Returns { "monitor": { … } }.
configreplaces the stored config, so send every setting you want to keep.- On an
http-statusmonitor, a newtarget_hostURL replaces the scheme, port and path in one go. - Changing the target or config resets the monitor to
pendingand runs the next check straight away. - Adding a
webhook_urlto a monitor without one generates a new webhook secret, returned once aswebhook_secretnext to the monitor. Send"webhook_url": nullto remove a webhook; its secret is discarded too, so adding a webhook again issues a fresh secret. - Resuming with
"paused": falsecounts against your plan's monitor limit, the same as in the dashboard.
curl -X PATCH https://www.tracewarrior.com/api/v1/monitors/00000000-0000-4000-8000-000000000000 \
-H "Authorization: Bearer tw_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "paused": true }'DELETE /api/v1/monitors/:id
Permanently delete a monitor and its entire check and alert history. Returns { "deleted": true }.
Monitor types and config
The type field selects what gets checked; config carries type-specific settings. Every config key is optional and falls back to the default shown; unknown keys are ignored. Invalid values are rejected with 400.
ssl-expiry: certificate expiry ontarget_host:target_port(port required, usually 443). Thresholds are whole days from 1 to 365, and the critical threshold can't be higher than the warning one.{ "alertWarningDays": 30, "alertCriticalDays": 7 }http-status: HTTP(S) response checks on a full URL.expectedStatustakes 1 to 10 codes from 100 to 599 (default[200]).bodyMatchis an optional string of up to 200 characters the body must contain.followRedirectsdefaults totrue; set it tofalseto alert when the URL redirects.{ "expectedStatus": [200, 204], "bodyMatch": "OK", "followRedirects": true }dns-record: watches records for drift against a baseline.recordTypesis any ofA,AAAA,MX,TXT,CNAMEandNS(default["A"]);resolveriscloudflare,googleorquad9. Names without address records, such as_dmarc.example.comor a DKIM selector under_domainkey, are fine.{ "recordTypes": ["A", "MX"], "resolver": "cloudflare" }port-tcp: TCP connect check ontarget_host:target_port(port required). No config. Port 25 is refused with a 400: outbound connections on it are blocked where the checks run, so the monitor could only ever fail. Use 465 or 587 for a mail server.whois-expiry: domain registration expiry, with the same thresholds asssl-expiry. Use the registered domain: a subdomain such aswww.example.comis stored asexample.com. Not available for.de,.eu,.es,.jp,.nland.audomains, whose registries don't publish expiry dates.{ "alertWarningDays": 30, "alertCriticalDays": 7 }ping: real ICMP reachability and latency from our London probe, over IPv4 or IPv6. Alerts on total loss (host down), high packet loss, or high round-trip latency.familyisauto,ipv4oripv6;lossWarnPctis 1 to 100 andlatencyWarnMs1 to 10000. Notarget_portneeded. Some hosts block ping; usehttp-statusorport-tcpfor those.{ "family": "auto", "lossWarnPct": 20, "latencyWarnMs": 250 }
interval_seconds minimums: 60 on Professional and Enterprise (the plans with API access), and 21600 (6 hours) for whois-expiry on every plan. The maximum is 2592000 (30 days). Private, internal and reserved hosts (RFC 1918, loopback, link-local, multicast, .local and similar) are rejected, both as monitor targets and in webhook URLs.
Webhooks
When a monitor with a webhook_url fires or recovers, we POST a JSON payload to it. The URL must be a public https:// (or http://) address; redirects are not followed. Slack and Discord webhook URLs get their native message formats. Every other URL gets this payload, with X-TraceWarrior-Event and X-TraceWarrior-Delivery headers:
{
"event": "monitor.fired",
"kind": "fired",
"severity": "critical",
"delivery_id": "…",
"fired_at": "2026-06-12T20:15:42.512Z",
"monitor": {
"id": "00000000-0000-4000-8000-000000000000",
"name": "Example SSL watch",
"type": "ssl-expiry",
"target": "example.com:443",
"url": "https://www.tracewarrior.com/dashboard/monitors/00000000-0000-4000-8000-000000000000"
},
"check": { "state": "critical", "summary": "…", "error": null, … },
"previous_state": "warning"
}The event field (and the X-TraceWarrior-Event header) is one of:
monitor.fired: the monitor entered awarning,criticalorerrorstate, or got worse.kindis"fired".monitor.recovered: the monitor is back took(sent whenrecovery_alertsis on).kindis"recovered"andseverityis"ok".monitor.test: a test delivery sent from the dashboard.
Test deliveries carry "kind": "test" and "test": true, a human-readable message, and a severity of "ok". They are signed the same way as real alerts, so you can use one to check your verification code, and are otherwise safe to ignore.
We sign the raw body. Verify the X-TraceWarrior-Signature header before trusting it: the value is sha256=<hex>, an HMAC-SHA256 of the request body using your monitor's webhook secret as the key. Compute it over the raw bytes, before any JSON parsing.
// Node.js verification
const crypto = require("node:crypto");
function isValidSignature(rawBody, signatureHeader, secret) {
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const a = Buffer.from(signatureHeader ?? "");
const b = Buffer.from(expected);
// timingSafeEqual throws when lengths differ, so check them first.
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Errors
Errors return { "error": "…" } with a meaningful status:
400Invalid input. The message names the field, e.g. target_port.401Missing, invalid or revoked API key.402Your plan doesn't include the feature, or you're at a plan limit.404Monitor not found on your account.429Too many requests, retry after a minute.500Unexpected server error, safe to retry.
Questions? Email support@tracewarrior.com.