API Reference The daemon exposes an HTTP API over its unix socket. When TCP is enabled, the same API is available over TLS with optional bearer token authentication. All responses are JSON.
Endpoints Status & Config Method Path Description Response GET/api/statusDaemon status, uptime, and collector intervals StatusResponseGET/api/configFull daemon, alerts, and TUI configuration ConfigResponse
Live Metrics Method Path Description Response GET/api/metrics/cpuPer-core CPU usage percentages CPUResponseGET/api/metrics/memoryMemory and swap usage MemoryMetricGET/api/metrics/diskPer-mount disk space, I/O rates, and SMART health DiskResponseGET/api/metrics/networkPer-interface throughput and error counters NetworkResponseGET/api/metrics/temperatureHardware sensor temperatures TemperatureResponseGET/api/metrics/powerPower consumption per RAPL zone PowerResponseGET/api/metrics/eccECC memory error counts ECCResponseGET/api/metrics/gpuGPU utilization, frequency, power, and memory GPUResponseGET/api/metrics/processAll processes (live in-memory snapshot) ProcessResponseGET/api/metrics/dashboardCombined overview of all metric types DashboardData
History All history endpoints accept ?start= and ?end= query parameters (Unix seconds). Bucket size auto-scales: 1 min (1h range) to 6 hr (30d range).
Query & Export Method Path Description Response POST/api/queryExecute a read-only SQL query QueryResponsePOST/api/exportExport query results to a file (CSV, Parquet, or JSON) ExportResponse
Examples get daemon status copy
curl --unix-socket /run/bewitch/bewitch.sock \
http://localhost/api/statusget CPU metrics copy
curl --unix-socket /run/bewitch/bewitch.sock \
http://localhost/api/metrics/cpuget history with time range copy
curl --unix-socket /run/bewitch/bewitch.sock \
"http://localhost/api/history/cpu?start=$(date -d '1 hour ago' +%s)&end=$(date +%s)"create alert rule copy
curl --unix-socket /run/bewitch/bewitch.sock \
-H 'Content-Type: application/json' \
-d '{
"name": "high-cpu",
"type": "threshold",
"severity": "warning",
"metric": "cpu.aggregate",
"operator": ">",
"value": 90,
"duration": "5m"
}' \
http://localhost/api/alert-rulesexecute SQL query copy
curl --unix-socket /run/bewitch/bewitch.sock \
-H 'Content-Type: application/json' \
-d '{"sql": "SELECT COUNT(*) as n FROM cpu_metrics"}' \
http://localhost/api/queryremote access (TCP + TLS + auth) copy
curl -k -H "Authorization: Bearer my-secret-token" \
https://myserver:9119/api/statusResponse Types Timestamps are int64 Unix nanoseconds. Arrays are always wrapped in objects. Errors return {"error": "message"}.
StatusResponse Field Type statusstringuptime_secnumberdefault_intervalstringcollector_intervalsmap<string, string>optional
DaemonConfigResponse Field Type socketstringdb_pathstringdefault_intervalstring
EmailDestResponse Field Type use_mail_cmdbooleanoptional smtp_hoststringoptional smtp_portnumberoptional fromstringoptional tostring[]
TUIConfigResponse Field Type refresh_intervalstring
CPUCoreMetric Field Type corenumberuser_pctnumbersystem_pctnumberidle_pctnumberiowait_pctnumber
MemoryMetric Field Type total_bytesnumberused_bytesnumberavailable_bytesnumberbuffers_bytesnumbercached_bytesnumberswap_total_bytesnumberswap_used_bytesnumber
DiskMetric Field Type mountstringdevicestringtransportstringoptional total_bytesnumberused_bytesnumberfree_bytesnumberread_bytes_secnumberwrite_bytes_secnumberread_iopsnumberwrite_iopsnumbersmart_availablebooleansmart_healthybooleanoptional smart_temperaturenumberoptional smart_power_on_hoursnumberoptional smart_power_cyclesnumberoptional smart_read_sectorsnumberoptional smart_written_sectorsnumberoptional smart_reallocatednumberoptional smart_pendingnumberoptional smart_uncorrectablenumberoptional smart_read_error_ratenumberoptional smart_available_sparenumberoptional smart_percent_usednumberoptional
NetworkMetric Field Type interfacestringrx_bytes_secnumbertx_bytes_secnumberrx_packets_secnumbertx_packets_secnumberrx_errorsnumbertx_errorsnumber
TemperatureMetric Field Type sensorstringtemp_celsiusnumber
PowerMetric Field Type zonestringwattsnumber
ECCMetric Field Type correctednumberuncorrectednumber
GPUResponse Field Type gpusGPUMetric[]hintsstring[]optional
GPUMetric Field Type namestringindexnumbervendorstringutilization_pctnumbermemory_used_bytesnumbermemory_total_bytesnumbertemp_celsiusnumberpower_wattsnumberfrequency_mhznumberfrequency_max_mhznumberthrottle_pctnumber
ProcessResponse Field Type processesProcessMetric[]total_procsnumberrunning_procsnumberactive_procsnumbertotal_cpu_pctnumbertotal_rss_bytesnumberenriched_countnumber
ProcessMetric Field Type pidnumberppidnumbernamestringcmdlinestringstatestringuidnumbercpu_user_pctnumbercpu_system_pctnumberrss_bytesnumbervss_bytesnumbershared_bytesnumberswap_bytesnumbernum_fdsnumbernum_threadsnumberstart_time_nsnumberenrichedboolean
TimeSeriesPoint Field Type timestamp_nsnumbervaluenumber
AlertMetric Field Type idnumbertimestampstringrule_namestringseveritystringmessagestringacknowledgedboolean
GenericResponse Field Type statusstringoptional errorstringoptional
AlertRuleMetric Field Type idnumbernamestringtypestringseveritystringenabledbooleanmetricstringoptional operatorstringoptional valuenumberoptional durationstringoptional mountstringoptional interface_namestringoptional sensorstringoptional predict_hoursnumberoptional threshold_pctnumberoptional delta_thresholdnumberoptional min_countnumberoptional process_namestringoptional process_patternstringoptional min_instancesnumberoptional restart_thresholdnumberoptional restart_windowstringoptional check_durationstringoptional
NotifyResult Field Type methodstringdeststringstatus_codenumberoptional latency_nsnumbererrorstringoptional bodystringoptional
QueryResponse Field Type columnsstring[]optional rowsany[][]optional errorstringoptional
ExportResponse Field Type row_countnumberpathstringerrorstringoptional
ExportRequest Field Type sqlstringpathstringformatstringoptional
SnapshotResponse Field Type pathstringsize_bytesnumbererrorstringoptional
SnapshotRequest Field Type pathstringwith_system_tablesbooleanoptional
ArchiveStatusItem Field Type table_namestringlast_archived_tsstring
PreferencesResponse Field Type itemsmap<string, string>
PreferenceRequest Field Type keystringvaluestring
ETag Caching Live metric endpoints include ETag headers. SendIf-None-Match to receive 304 Not Modified when data hasn't changed.