diff --git a/frontend/src/pages/engineering/developer/ApiReferencePage.jsx b/frontend/src/pages/engineering/developer/ApiReferencePage.jsx
index fc68567..125b5d8 100644
--- a/frontend/src/pages/engineering/developer/ApiReferencePage.jsx
+++ b/frontend/src/pages/engineering/developer/ApiReferencePage.jsx
@@ -1516,6 +1516,31 @@ function TransportsTab() {
         </div>
       </Card>
 
+      <Card title="Heartbeat Payload" subtitle="Published every 30 s to vesper/{device_id}/status/heartbeat — retained, QoS 1">
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-4)' }}>
+          <MonoBlock code={'{\n  "status": "INFO",\n  "type": "heartbeat",\n  "payload": {\n    "device_id":        "PV-26B18-VS01R-X7KQA",\n    "firmware_version": "142",\n    "timestamp":        "Uptime: 5h 23m 45s",\n    "ip_address":       "10.0.0.3",\n    "gateway":          "10.0.0.1",\n    "uptime_ms":        19425000,\n    "rssi":             -62\n  }\n}'} />
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(160px, 1fr))', gap: 'var(--space-3)' }}>
+            {[
+              { field: 'device_id',        type: 'string', notes: 'Serial number from NVS.' },
+              { field: 'firmware_version', type: 'string', notes: 'FW_VERSION constant compiled into the binary.' },
+              { field: 'timestamp',        type: 'string', notes: 'Human-readable uptime string, e.g. "Uptime: 5h 23m 45s".' },
+              { field: 'ip_address',       type: 'string', notes: 'Current WiFi IP address.' },
+              { field: 'gateway',          type: 'string', notes: 'Current gateway IP address.' },
+              { field: 'uptime_ms',        type: 'int',    notes: 'Milliseconds since last boot (millis()).' },
+              { field: 'rssi',             type: 'int',    notes: 'WiFi signal strength in dBm. Typical range: -30 (excellent) to -90 (weak).' },
+            ].map(row => (
+              <div key={row.field} style={{ padding: 'var(--space-3)', borderRadius: 'var(--radius-md)', backgroundColor: 'var(--color-bg-elevated)', border: '1px solid var(--color-border)' }}>
+                <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)', marginBottom: 'var(--space-1)' }}>
+                  <span style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-sm)', color: 'var(--color-primary)' }}>{row.field}</span>
+                  <span style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-xs)', color: 'var(--color-info)' }}>{row.type}</span>
+                </div>
+                <p style={{ margin: 0, fontSize: 'var(--font-size-sm)', color: 'var(--color-text-muted)' }}>{row.notes}</p>
+              </div>
+            ))}
+          </div>
+        </div>
+      </Card>
+
       <Card title="UART Whitelist" subtitle="Commands permitted on the hardware serial interface">
         <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--space-2)' }}>
           {UART_WHITELIST.map(cmd => (