Skip to content
trace·warrior
Code window with an arrow to a key, then servers connecting out to three screens
updated · 2026-11-01

How to use the Trace Warrior monitor API

Create, list, pause, and delete monitors over REST. Authentication with API keys, request examples with curl, and webhook signature verification.

monitoringapiTrace Warrior Team
4 min read

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

  1. Sign in and open Dashboard → Profile.
  2. In the API keys section, name the key after the thing that will use it (ci-pipeline, terraform, onboarding-script) and create it.
  3. 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

StatusMeaning
400Validation failure (bad type, interval below the floor, private target, body that isn't a JSON object)
401Missing, invalid, or revoked API key
402Plan limit: monitor quota reached, or API access not on your plan
404Monitor doesn't exist or belongs to another account
429Too many requests, retry after a minute
500Unexpected 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.