bewitch

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

MethodPathDescriptionResponse
GET /api/status Daemon status, uptime, and collector intervals StatusResponse
GET /api/config Full daemon, alerts, and TUI configuration ConfigResponse

Live Metrics

MethodPathDescriptionResponse
GET /api/metrics/cpu Per-core CPU usage percentages CPUResponse
GET /api/metrics/memory Memory and swap usage MemoryMetric
GET /api/metrics/disk Per-mount disk space, I/O rates, and SMART health DiskResponse
GET /api/metrics/network Per-interface throughput and error counters NetworkResponse
GET /api/metrics/temperature Hardware sensor temperatures TemperatureResponse
GET /api/metrics/power Power consumption per RAPL zone PowerResponse
GET /api/metrics/ecc ECC memory error counts ECCResponse
GET /api/metrics/gpu GPU utilization, frequency, power, and memory GPUResponse
GET /api/metrics/process All processes (live in-memory snapshot) ProcessResponse
GET /api/metrics/dashboard Combined 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).

MethodPathDescriptionResponse
GET /api/history/cpu CPU usage over time HistoryResponse
GET /api/history/memory Memory usage over time HistoryResponse
GET /api/history/disk Disk space and I/O over time HistoryResponse
GET /api/history/network Network throughput over time HistoryResponse
GET /api/history/temperature Temperature over time HistoryResponse
GET /api/history/power Power consumption over time HistoryResponse
GET /api/history/gpu GPU metrics over time HistoryResponse
GET /api/history/process Top processes by CPU over time HistoryResponse

Alerts

MethodPathDescriptionResponse
GET /api/alerts List fired alerts AlertsResponse
POST /api/alerts/{id}/ack Acknowledge a fired alert GenericResponse
GET /api/alert-rules List all alert rules AlertRulesResponse
POST /api/alert-rules Create a new alert rule GenericResponse
DELETE /api/alert-rules/{id} Delete an alert rule GenericResponse
PUT /api/alert-rules/{id}/toggle Toggle a rule enabled/disabled GenericResponse
POST /api/test-notifications Send a test alert to all notification channels NotifyTestResponse

Query & Export

MethodPathDescriptionResponse
POST /api/query Execute a read-only SQL query QueryResponse
POST /api/export Export query results to a file (CSV, Parquet, or JSON) ExportResponse

Data Management

MethodPathDescriptionResponse
POST /api/compact Trigger database compaction GenericResponse
POST /api/snapshot Create a standalone database snapshot SnapshotResponse
POST /api/archive Trigger Parquet archival of old data GenericResponse
POST /api/unarchive Reload Parquet data into the database GenericResponse
GET /api/archive/status Archive state and directory statistics ArchiveStatusResponse

Preferences

MethodPathDescriptionResponse
GET /api/preferences Get all saved preferences PreferencesResponse
POST /api/preferences Set a preference key/value pair GenericResponse

Examples🔗

# get daemon status
curl --unix-socket /run/bewitch/bewitch.sock \
  http://localhost/api/status
# get CPU metrics
curl --unix-socket /run/bewitch/bewitch.sock \
  http://localhost/api/metrics/cpu
# get history with time range
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
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-rules
# execute SQL query
curl --unix-socket /run/bewitch/bewitch.sock \
  -H 'Content-Type: application/json' \
  -d '{"sql": "SELECT COUNT(*) as n FROM cpu_metrics"}' \
  http://localhost/api/query
# remote access (TCP + TLS + auth)
curl -k -H "Authorization: Bearer my-secret-token" \
  https://myserver:9119/api/status

Response Types🔗

Timestamps are int64 Unix nanoseconds. Arrays are always wrapped in objects. Errors return {"error": "message"}.

AlertMetric

FieldType
idnumber
timestampstring
rule_namestring
severitystring
messagestring
acknowledgedboolean

AlertRuleMetric

FieldType
idnumber
namestring
typestring
severitystring
enabledboolean
metricstringoptional
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

AlertRulesResponse

FieldType
rulesAlertRuleMetric[]

AlertsConfigResponse

FieldType
evaluation_intervalstring
emailEmailDestResponse[]optional
commandsCommandDestResponse[]optional

AlertsResponse

FieldType
alertsAlertMetric[]

ArchiveStatusItem

FieldType
table_namestring
last_archived_tsstring

ArchiveStatusResponse

FieldType
tablesArchiveStatusItem[]
total_filesnumber
total_bytesnumber

CPUCoreMetric

FieldType
corenumber
user_pctnumber
system_pctnumber
idle_pctnumber
iowait_pctnumber

CPUResponse

FieldType
coresCPUCoreMetric[]

CommandDestResponse

FieldType
cmdstring

ConfigResponse

FieldType
daemonDaemonConfigResponse
alertsAlertsConfigResponse
tuiTUIConfigResponse

DaemonConfigResponse

FieldType
socketstring
db_pathstring
default_intervalstring

DashboardData

FieldType
cpuCPUCoreMetric[]
memoryMemoryMetricoptional
disksDiskMetric[]
networkNetworkMetric[]
temperatureTemperatureMetric[]
powerPowerMetric[]
gpuGPUMetric[]optional
processesProcessResponseoptional

DiskMetric

FieldType
mountstring
devicestring
transportstringoptional
total_bytesnumber
used_bytesnumber
free_bytesnumber
read_bytes_secnumber
write_bytes_secnumber
read_iopsnumber
write_iopsnumber
smart_availableboolean
smart_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

DiskResponse

FieldType
disksDiskMetric[]

ECCMetric

FieldType
correctednumber
uncorrectednumber

ECCResponse

FieldType
eccECCMetric

EmailDestResponse

FieldType
use_mail_cmdbooleanoptional
smtp_hoststringoptional
smtp_portnumberoptional
fromstringoptional
tostring[]

ExportRequest

FieldType
sqlstring
pathstring
formatstringoptional

ExportResponse

FieldType
row_countnumber
pathstring
errorstringoptional

GPUMetric

FieldType
namestring
indexnumber
vendorstring
utilization_pctnumber
memory_used_bytesnumber
memory_total_bytesnumber
temp_celsiusnumber
power_wattsnumber
frequency_mhznumber
frequency_max_mhznumber
throttle_pctnumber

GPUResponse

FieldType
gpusGPUMetric[]
hintsstring[]optional

GenericResponse

FieldType
statusstringoptional
errorstringoptional

HistoryResponse

FieldType
seriesTimeSeries[]

MemoryMetric

FieldType
total_bytesnumber
used_bytesnumber
available_bytesnumber
buffers_bytesnumber
cached_bytesnumber
swap_total_bytesnumber
swap_used_bytesnumber

NetworkMetric

FieldType
interfacestring
rx_bytes_secnumber
tx_bytes_secnumber
rx_packets_secnumber
tx_packets_secnumber
rx_errorsnumber
tx_errorsnumber

NetworkResponse

FieldType
interfacesNetworkMetric[]

NotifyResult

FieldType
methodstring
deststring
status_codenumberoptional
latency_nsnumber
errorstringoptional
bodystringoptional

NotifyTestResponse

FieldType
resultsNotifyResult[]

PowerMetric

FieldType
zonestring
wattsnumber

PowerResponse

FieldType
zonesPowerMetric[]

PreferenceRequest

FieldType
keystring
valuestring

PreferencesResponse

FieldType
itemsmap<string, string>

ProcessMetric

FieldType
pidnumber
ppidnumber
namestring
cmdlinestring
statestring
uidnumber
cpu_user_pctnumber
cpu_system_pctnumber
rss_bytesnumber
vss_bytesnumber
shared_bytesnumber
swap_bytesnumber
num_fdsnumber
num_threadsnumber
start_time_nsnumber
enrichedboolean

ProcessResponse

FieldType
processesProcessMetric[]
total_procsnumber
running_procsnumber
active_procsnumber
total_cpu_pctnumber
total_rss_bytesnumber
enriched_countnumber

QueryRequest

FieldType
sqlstring

QueryResponse

FieldType
columnsstring[]optional
rowsany[][]optional
errorstringoptional

SnapshotRequest

FieldType
pathstring
with_system_tablesbooleanoptional

SnapshotResponse

FieldType
pathstring
size_bytesnumber
errorstringoptional

StatusResponse

FieldType
statusstring
uptime_secnumber
default_intervalstring
collector_intervalsmap<string, string>optional

TUIConfigResponse

FieldType
refresh_intervalstring

TemperatureMetric

FieldType
sensorstring
temp_celsiusnumber

TemperatureResponse

FieldType
sensorsTemperatureMetric[]

TimeSeries

FieldType
labelstring
pointsTimeSeriesPoint[]

TimeSeriesPoint

FieldType
timestamp_nsnumber
valuenumber

ETag Caching🔗

Live metric endpoints include ETag headers. Send If-None-Match to receive 304 Not Modified when data hasn't changed.