POST /api/govern/probe/heartbeat

Endpoint

POST https://api.govern.archetypal.ai/api/govern/probe/heartbeat

The Probe sends a heartbeat every 60 seconds to register itself with the GOVERN platform and report current status. This powers the “Active Probes” view in the dashboard.

Authentication

Authorization: Bearer gvn_live_xxxxxxxxxxxx
X-Govern-Org-Id: org_xxxxxxxxxxxx

Request body

{
  "probe_id": "probe-production-1",
  "org_id": "org_xxxx",
  "version": "1.2.0",
  "timestamp": "2026-04-12T14:23:00.000Z",
  "status": "healthy",
  "config": {
    "upstream_url": "https://api.anthropic.com",
    "scoring_mode": "flag",
    "environment": "production"
  },
  "stats": {
    "uptime_seconds": 3847,
    "inferences_total": 1247,
    "inferences_per_minute": 4.2,
    "ring_buffer_utilization": 0.12,
    "telemetry_lag_ms": 0,
    "last_flush_at": "2026-04-12T14:22:55.000Z",
    "scoring_latency_p50_ms": 12,
    "proxy_latency_p50_ms": 3.2
  }
}

Response

Success (200 OK):

{
  "acknowledged": true,
  "probe_id": "probe-production-1",
  "policy_version": "v3",
  "policy_updated": false,
  "next_heartbeat_ms": 60000
}

When policy_updated is true, the Probe fetches updated policy from the policy sync endpoint.

Probe registration

The first heartbeat from a new probe_id registers the Probe in the GOVERN platform. It appears in the dashboard under Settings → Probes within 60 seconds.

If probe_id is not set (GOVERN_PROBE_ID not configured), the Probe auto-generates a UUID on startup and includes it in every heartbeat. The UUID is stable for the container’s lifetime but regenerates on restart.

Heartbeat interval

Default: 60 seconds. Configurable:

govern:
  heartbeat_interval_ms: 60000

Minimum: 10 seconds (enforced by the platform — faster heartbeats are rejected).