OpenGuardrailsOpenGuardrails

POST /v1/heartbeat

Integration liveness over the authenticated channel. Uninstalling or silencing an integration is the cheapest bypass there is, and without a beat the runtime cannot distinguish "agent idle" (fine) from "integration went dark" (a coverage loss). The heartbeat keeps those two facts apart.

A heartbeat is transport-level: it is not a GuardEvent and carries no guarded action. This is also where the integration build id's liveness copy lives — fleet coverage reads it from here. (The event carries its own optional integration copy for per-event triage: the heartbeat goes quiet exactly when a bad rollout is what you are naming.)

POST {base_url}/v1/heartbeat
Authorization: Bearer ogr_<key>
Content-Type: application/json

Request

At least one of integration / agent_id must be present.

{
  "integration": "ogr-higress/3.0.0",
  "agent_id": "invoice-bot",
  "interval_s": 30,
  "counters": {"events_sent": 120, "evaluate_errors": 0, "unresolved_spans": 0}
}
FieldTypeRequiredDescription
integrationstringone-ofThe integration identifying itself — name and build, e.g. my-harness/1.2.0
agent_idstringone-ofThe agent whose liveness rides this beat
interval_snumberoptionalDeclared cadence; lets the runtime compute "missed beats"
countersobjectoptionalFree-form counters — events_sent, evaluate_errors, unresolved_spans, …

evaluate_errors is how the runtime learns an integration entered degraded mode: events observed while the runtime was unreachable are lost observations (the protocol has no replay channel), and the counters are what make the gap visible instead of silent. unresolved_spans counts modification spans the integration could not apply — "no spans resolved" is otherwise indistinguishable from "no redaction policy".

Response — 200

{ "ok": true }

A heartbeat registers a live-but-idle agent: fleet coverage reflects integrations that have not yet emitted a single event. Deploy the integration, start the beat, and the runtime knows the surface is covered before the first guarded action arrives.

Example

curl -s $OGR_RUNTIME/v1/heartbeat \
  -H "Authorization: Bearer $OGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration": "my-harness/1.0.0", "agent_id": "invoice-bot", "interval_s": 30}'

Operational semantics

  • A runtime alerts when an integration misses beats beyond a tolerance, and treats the gap as a coverage loss — never as "no risk".
  • counters reconciled against delivered events is what makes selective event suppression detectable: an integration reporting N sent while N−k arrived is a finding, not noise.