Heartbeat — dead-man switch for cron jobs & AI agents

Arm a new dead-man switch monitor. Returns the key plus a ping_url your job must hit after every run. No account needed. Names are globally unique on this instance and each name gets a PUBLIC status page; the secret key is the only credential — keep it.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "unique name, 1-40 chars [A-Za-z0-9_.-]"
    },
    "period_s": {
      "type": "integer",
      "description": "expected seconds between pings (60-86400)",
      "default": 300
    },
    "grace_s": {
      "type": "integer",
      "description": "extra seconds of slack before DOWN (0-86400)",
      "default": 300
    },
    "kind": {
      "type": "string",
      "enum": [
        "push",
        "pull",
        "selfcheck"
      ],
      "description": "push = you ping us; pull = we probe target_url every min(period_s,60)s; selfcheck = your box runs our egress-trust probe script and POSTs verdict reports to the ping URL",
      "default": "push"
    },
    "target_url": {
      "type": "string",
      "description": "public http(s) URL to probe (pull only)"
    },
    "webhook_url": {
      "type": "string",
      "description": "public http(s) URL that receives UP/DOWN alerts (optional)"
    },
    "depends_on": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "parent monitor names and/or gate:<gate-name> entries (max 5). When a parent is DOWN or a gate parent is HALT this monitor becomes DEGRADED-BY-UPSTREAM: notified once, own silence paging suppressed until the parent recovers."
    },
    "pass_key": {
      "type": "string",
      "description": "Pro pass key from a $5 USDC payment (optional; skips rate limits)"
    }
  },
  "required": [
    "name"
  ]
}

Record one successful run for a monitor (same as GETting https://golemreach.com/heartbeat/ping/<key>). Call this every time your job runs. For kind=selfcheck monitors pass an 'endpoints' array of {"name","status_code","cf_mitigated","tls_ms"} objects instead — alerts fire on trusted->challenged / recovery transitions only.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "monitor key returned by create_heartbeat"
    },
    "endpoints": {
      "type": "array",
      "description": "selfcheck monitors only: one object per probed surface, e.g. {\"name\":\"claude-session\",\"status_code\":200,\"cf_mitigated\":false,\"tls_ms\":230}",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "status_code": {
            "type": "integer"
          },
          "cf_mitigated": {
            "type": "boolean"
          },
          "tls_ms": {
            "type": "integer"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "trusted",
              "rate_limited",
              "error",
              "challenged"
            ]
          }
        },
        "required": [
          "name"
        ]
      }
    }
  },
  "required": [
    "key"
  ]
}

Explicitly mark a run as FAILED for a monitor (same as GET https://golemreach.com/heartbeat/fail/<key>). The monitor goes DOWN immediately and alerts fire.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string"
    }
  },
  "required": [
    "key"
  ]
}

List monitors on this Heartbeat instance with current status (new/up/late/down). Names and statuses are public by design — every monitor has a public status page. Pass your secret key to also include that monitor's private ping/fail URLs in the result.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "optional monitor key; adds the private ping_url/fail_url for that one monitor"
    }
  }
}

Full current state of one monitor: status, 30-day uptime %, schedule, last ping, alert config, recent event history and its public URLs. Look up by name OR by your secret key; key lookups additionally return the private ping/fail URLs.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "monitor name (public lookup)"
    },
    "key": {
      "type": "string",
      "description": "monitor key (private lookup; also returns ping/fail URLs)"
    }
  }
}