Skip to content
trace·warrior
docs

Monitor API

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": { … } }.

  • config replaces the stored config, so send every setting you want to keep.
  • On an http-status monitor, a new target_host URL replaces the scheme, port and path in one go.
  • Changing the target or config resets the monitor to pending and runs the next check straight away.
  • Adding a webhook_url to a monitor without one generates a new webhook secret, returned once as webhook_secret next to the monitor. Send "webhook_url": null to remove a webhook; its secret is discarded too, so adding a webhook again issues a fresh secret.
  • Resuming with "paused": false counts 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 on target_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. expectedStatus takes 1 to 10 codes from 100 to 599 (default [200]). bodyMatch is an optional string of up to 200 characters the body must contain. followRedirects defaults to true; set it to false to alert when the URL redirects.

    { "expectedStatus": [200, 204], "bodyMatch": "OK", "followRedirects": true }
  • dns-record: watches records for drift against a baseline. recordTypes is any of A, AAAA, MX, TXT, CNAME and NS (default ["A"]); resolver is cloudflare, google or quad9. Names without address records, such as _dmarc.example.com or a DKIM selector under _domainkey, are fine.

    { "recordTypes": ["A", "MX"], "resolver": "cloudflare" }
  • port-tcp: TCP connect check on target_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 as ssl-expiry. Use the registered domain: a subdomain such as www.example.com is stored as example.com. Not available for .de, .eu, .es, .jp, .nl and .au domains, 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. family is auto, ipv4 or ipv6; lossWarnPct is 1 to 100 and latencyWarnMs 1 to 10000. No target_port needed. Some hosts block ping; use http-status or port-tcp for 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 a warning, critical or error state, or got worse. kind is "fired".
  • monitor.recovered: the monitor is back to ok (sent when recovery_alerts is on). kind is "recovered" and severity is "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.