Health API
GET /api/health returns a canonical HealthStatus object for unattended
exhibition monitoring. The shape is defined by
health-status.schema.json in the player API contract.
{
"device_id": "gallery-a",
"sampled_at_unix_ms": 1785686400000,
"uptime_sec": 3600,
"overall_ok": true,
"control": {
"http": { "enabled": true, "ok": true, "error": null },
"osc": { "enabled": true, "ok": true, "error": null }
},
"render": {
"main_loop_fps": 60.0,
"render_fps": 60.0
},
"display": {
"ok": true,
"inhibit_requested": true,
"screensaver_inhibited": true,
"error": null
},
"playback": {
"ok": true,
"state": "playing",
"error_code": null
},
"system": {
"ok": true,
"clock_synchronized": true,
"disk_total_bytes": 64000000000,
"disk_free_bytes": 32000000000,
"temperature_c": 52.5,
"error": null
}
}Top-level fields
| Field | Type | Description |
|---|---|---|
device_id | string | Stable device identifier (topic segment). |
sampled_at_unix_ms | int | Wall-clock sample time for display only—not for ordering. |
uptime_sec | number | Process uptime from a monotonic clock (NTP-safe). |
overall_ok | bool | Conjunction of enabled control transports plus display, playback, and system health. |
control | object | HTTP/OSC listener health slots. |
render | object | Render FPS telemetry. |
display | object | Screensaver / DPMS inhibition status. |
playback | object | Last known playback state and error. |
system | object | Optional platform telemetry (null when unavailable). |
Disabled transports use enabled=false, ok=true, error=null—configuration off,
not a fault.
Control health (control)
Each slot reports enabled, ok, and error (string or null). No ports
or allowlists are exposed on this public endpoint.
Render health (render)
Reports measured main-loop and present rates. It is telemetry only and does not classify a frame as frozen or decide whether the process should be restarted.
| Field | Description |
|---|---|
main_loop_fps / render_fps | Smoothed loop and present rates. |
Display health (display)
| Field | Description |
|---|---|
ok | Screensaver inhibition succeeded. |
inhibit_requested | Always true; the player always requests inhibition. |
screensaver_inhibited | OS inhibition is active. |
error | Fault when inhibition failed. |
Playback health (playback)
| Field | Description |
|---|---|
ok | No active playback fault. |
state | Current public state (idle … error). |
error_code | Catalog error code or null. |
Playback health does not replace GET /api/status for position and metadata.
System health (system)
Fixed nullable slots—use null when the platform cannot measure a value:
| Field | Description |
|---|---|
clock_synchronized | NTP/RTC sync hint for Pi diagnostics. |
disk_total_bytes / disk_free_bytes | Storage headroom when available. |
temperature_c | SoC temperature when available. |
error | Platform fault string or null. |
Unknown temperature, disk, or clock state does not fail system.ok unless
the platform reports an explicit fault.
Monitoring use cases
Health monitoring
Poll /api/health when an external monitor needs playback, display, or control
diagnostics. Render fields are measurements; any restart policy belongs to the
external process supervisor.
Fleet dashboards
Poll at 1–5 s intervals for fleet dashboards.
Previous / Next
- Previous: Status API
- Next: Maintenance status