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
`GET`	`/api/status`	Daemon status and uptime
`GET`	`/api/config`	Full configuration

Live Metrics

Method	Path	Description
`GET`	`/api/metrics/cpu`	CPU per-core metrics
`GET`	`/api/metrics/memory`	Memory metrics
`GET`	`/api/metrics/disk`	Disk space, I/O, SMART health
`GET`	`/api/metrics/network`	Network per-interface metrics
`GET`	`/api/metrics/temperature`	Temperature sensor readings
`GET`	`/api/metrics/power`	Power consumption per zone
`GET`	`/api/metrics/gpu`	GPU utilization, frequency, power, memory
`GET`	`/api/metrics/process`	All processes (live snapshot)
`GET`	`/api/metrics/dashboard`	Combined dashboard data

History

All history endpoints accept ?start=&end= query parameters (Unix seconds). Bucket size auto-scales: 1 min (1h range) to 6 hr (30d range).

Method	Path
`GET`	`/api/history/cpu`
`GET`	`/api/history/memory`
`GET`	`/api/history/disk`
`GET`	`/api/history/temperature`
`GET`	`/api/history/power`
`GET`	`/api/history/gpu`
`GET`	`/api/history/process`

Alerts

Method	Path	Description
`GET`	`/api/alerts`	List alerts (`?ack=false` for unacknowledged)
`POST`	`/api/alerts/{id}/ack`	Acknowledge an alert
`GET`	`/api/alert-rules`	List all rules
`POST`	`/api/alert-rules`	Create a rule
`DELETE`	`/api/alert-rules/{id}`	Delete a rule
`PUT`	`/api/alert-rules/{id}/toggle`	Toggle rule enabled/disabled
`POST`	`/api/test-notifications`	Test all notification channels

Query & Export

Method	Path	Description
`POST`	`/api/query`	Execute read-only SQL
`POST`	`/api/export`	Export query results to file

Data Management

Method	Path	Description
`POST`	`/api/compact`	Trigger database compaction
`POST`	`/api/snapshot`	Create standalone DuckDB snapshot
`POST`	`/api/archive`	Trigger Parquet archival
`POST`	`/api/unarchive`	Reload Parquet data into DuckDB
`GET`	`/api/archive/status`	Archive state and directory stats

Preferences

Method	Path	Description
`GET`	`/api/preferences`	Get all saved preferences
`POST`	`/api/preferences`	Set a preference (key/value)

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

ETag Caching

Metric and process endpoints include ETag headers (generation counters). Clients can sendIf-None-Match to receive 304 Not Modified when data hasn't changed, avoiding unnecessary serialization and transfer.

Response Format

All responses are JSON. Arrays are wrapped in objects (e.g., {"cores": [...]} not bare [...]). Timestamps are int64 Unix nanoseconds. Errors return{"error": "message"}.