The monitor API lets you manage Trace Warrior monitors from scripts, CI pipelines, and provisioning tools instead of the dashboard. Spin up an SSL-expiry monitor for every new client domain in your onboarding script, pause checks during planned maintenance, or tear monitors down when a project ends.
API access is included in the Professional plan and above.
Full reference: Monitor API docs.
Get an API key
- Sign in and open Dashboard → Profile.
- In the API keys section, name the key after the thing that will use it (
ci-pipeline,terraform,onboarding-script) and create it. - Copy the key immediately; it's shown once and stored only as a hash. If you lose it, revoke it and create a new one.
Keys look like tw_… and are sent as a bearer token:
export TW_API_KEY="tw_your-key-here"
You can hold up to 5 active keys, so each system gets its own; revoke one without breaking the others.
List monitors
curl -s https://www.tracewarrior.com/api/v1/monitors \
-H "Authorization: Bearer $TW_API_KEY"
Returns every monitor on the account (trimmed here; the API docs list every field):
{
"monitors": [
{
"id": "9b2e…",
"name": "example.com cert",
"type": "ssl-expiry",
"target_host": "example.com",
"target_port": 443,
"interval_seconds": 86400,
"state": "ok",
"paused": false,
"last_check_at": "2026-06-10T09:23:03.412871+00:00",
"next_check_at": "2026-06-11T09:23:03.412871+00:00"
}
]
}
Create a monitor
curl -s -X POST https://www.tracewarrior.com/api/v1/monitors \
-H "Authorization: Bearer $TW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "example.com cert",
"type": "ssl-expiry",
"target_host": "example.com",
"target_port": 443,
"interval_seconds": 86400,
"email_alerts": true
}'
This example works as pasted: example.com is reserved for documentation and resolves in public DNS. Swap in your own host. The target, and the host in any webhook_url, must resolve in public DNS, or the request gets a 400. To get webhook alerts too, add "webhook_url" with your own public HTTPS endpoint.
The six type values are ssl-expiry, dns-record, port-tcp, http-status, whois-expiry, and ping, the same checks described on the monitors page. interval_seconds is floored by your plan (60s on Professional) and, for whois-expiry, by the type itself (6 hours). Plan quota and target validation are enforced exactly as in the dashboard; private, loopback and other reserved addresses are rejected.
For http-status, target_host may be a full URL such as https://example.com/health. The scheme, port and path are kept, so you can leave target_port and target_path out. A bare hostname is checked over HTTPS.
A 201 response returns the created monitor plus, if you set a webhook_url, a one-time webhook_secret for signature verification. Slack and Discord webhook URLs work too; they get their native message formats instead of signed JSON.
Update or pause a monitor
PATCH accepts any of name, target_host, target_port, target_path, config, interval_seconds, email_alerts, recovery_alerts, webhook_url, and paused. Changing the target or config resets the monitor's baseline and runs the next check immediately. On an http-status monitor, target_host re-specifies the whole URL, so send the full URL (for example https://example.com/health). Anything it leaves out is taken from target_port/target_path in the same request, not kept from the existing monitor, and a bare hostname means HTTPS unless the same request sets config.scheme.
Adding a webhook_url to a monitor without one generates a new signing secret, returned once as webhook_secret in the PATCH response. Store it straight away; it isn't shown again. Changing an existing webhook URL keeps its secret; removing the webhook ("webhook_url": null) discards it, so adding a webhook again issues a fresh secret.
# Pause during planned maintenance
curl -s -X PATCH https://www.tracewarrior.com/api/v1/monitors/$MONITOR_ID \
-H "Authorization: Bearer $TW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"paused": true}'
Unpausing ("paused": false) schedules the next check immediately. A resumed monitor counts toward your plan's monitor limit again, so unpausing returns 402 if you're already at it.
Delete a monitor
curl -s -X DELETE https://www.tracewarrior.com/api/v1/monitors/$MONITOR_ID \
-H "Authorization: Bearer $TW_API_KEY"
Deletion also removes the monitor's check history and alert log.
Verify webhook signatures
Generic (non-Slack/Discord) webhook deliveries are signed with HMAC-SHA256 over the raw request body, using the webhook_secret returned when the monitor first got a webhook (on create, or on the PATCH that added a webhook to a monitor without one). The signature arrives in the X-TraceWarrior-Signature header as sha256=<hex>:
import crypto from "node:crypto";
function verify(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 the lengths differ, so a missing or
// garbled header must fail the length check instead of crashing.
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Always compute the HMAC over the raw bytes, before any JSON parsing; re-serialised JSON will not match. See how to test webhook endpoints for a full testing workflow.
Error responses
| Status | Meaning |
|---|---|
400 | Validation failure (bad type, interval below the floor, private target, body that isn't a JSON object) |
401 | Missing, invalid, or revoked API key |
402 | Plan limit: monitor quota reached, or API access not on your plan |
404 | Monitor doesn't exist or belongs to another account |
429 | Too many requests, retry after a minute |
500 | Unexpected server error, safe to retry |
Errors are JSON: {"error": "Monitor not found."}
TL;DR
Create a key in Dashboard → Profile, send it as Authorization: Bearer tw_…, and hit /api/v1/monitors for list/create and /api/v1/monitors/:id for get/patch/delete. Same plan rules as the dashboard, JSON in and out, webhook secrets shown once. If something's unclear, tell us.
