bee/bible-local/architecture/api-surface.md

API Surface

HTTP endpoints exposed by bee web (binds 0.0.0.0:80). Handler registration: audit/internal/webui/server.go → NewHandler().

---

Health & readiness

Method	Path	Description
GET	/healthz	Always 200. Used by load balancers / boot scripts.
GET	/api/ready	200 when audit JSON exists and is readable.
GET	/loading	HTML loading page shown before first audit.

---

Audit

Method	Path	Description
GET	/audit.json	Latest audit JSON with SAT overlay applied.
GET	/runtime-health.json	Latest runtime preflight JSON.
POST	/api/audit/run	Enqueue a full bee audit run. Returns task ID.
GET	/api/audit/stream	SSE: audit run log lines (data: + newline per line).
GET	/api/preflight	Run runtime preflight check (synchronous, returns JSON).
GET	/api/hardware-summary	Hardware health summary (status counts + failures).
GET	/api/components/{type}	HTML fragment for component detail dialog (e.g. cpu, memory, storage, pcie).

---

SAT (System Acceptance Testing)

All SAT run endpoints enqueue an async task. Response: {"task_id": "..."}.

Method	Path	Description
POST	/api/sat/nvidia/run	NVIDIA DCGM SAT
POST	/api/sat/nvidia-targeted-stress/run	NVIDIA targeted stress validate
POST	/api/sat/nvidia-compute/run	NVIDIA max compute load
POST	/api/sat/nvidia-targeted-power/run	NVIDIA targeted power
POST	/api/sat/nvidia-pulse/run	NVIDIA pulse test
POST	/api/sat/nvidia-interconnect/run	NCCL all_reduce_perf
POST	/api/sat/nvidia-bandwidth/run	NVBandwidth + PCIe link under load
POST	/api/sat/nvidia-stress/run	NVIDIA stress pack
POST	/api/sat/memory/run	Memory acceptance
POST	/api/sat/storage/run	Storage acceptance (smartctl)
POST	/api/sat/cpu/run	CPU acceptance (stress-ng)
POST	/api/sat/amd/run	AMD GPU SAT (ROCm)
POST	/api/sat/amd-mem/run	AMD memory integrity + bandwidth
POST	/api/sat/amd-bandwidth/run	AMD memory bandwidth
POST	/api/sat/amd-stress/run	AMD GPU stress
POST	/api/sat/memory-stress/run	Memory stress
POST	/api/sat/sat-stress/run	Combined storage+memory stress
POST	/api/sat/platform-stress/run	Fan + thermal stress
POST	/api/sat/fan/run	Fan ceiling check (CPU+GPU load until fans plateau; Load tier). Not-applicable → task cancelled, not failed.
POST	/api/sat/run-all	Plan + enqueue the whole validate/check set server-side. Body: {stress_mode, amd_targets[], nvidia_gpu_indices[]} (operator intent only). Response: {task_ids[], task_count, notes[]}. Hardware presence/readiness and which tasks to run are decided by handler.planSATRunAll, not the page.
GET	/api/sat/stream	SSE: live SAT log stream
POST	/api/sat/abort	Abort the running SAT task

---

Benchmarks

Method	Path	Description
POST	/api/bee-bench/nvidia/perf/run	NVIDIA performance benchmark
POST	/api/bee-bench/nvidia/power/run	NVIDIA power benchmark
POST	/api/bee-bench/nvidia/autotune/run	Power source autotune (prerequisite for benchmarks)
GET	/api/bee-bench/nvidia/autotune/status	Current autotune result / status
GET	/api/benchmark/results	List completed benchmark result archives

---

Tasks (async job queue)

Method	Path	Description
GET	/api/tasks	List all tasks with status
POST	/api/tasks/cancel-all	Cancel all pending/running tasks
POST	/api/tasks/kill-workers	Force-kill worker goroutines
POST	/api/tasks/{id}/cancel	Cancel a specific task
POST	/api/tasks/{id}/priority	Elevate task priority
GET	/api/tasks/{id}/stream	SSE: live log stream for a task
GET	/api/tasks/{id}/charts	List chart names for a task
GET	/api/tasks/{id}/chart/	SVG chart for a task result
GET	/tasks/{id}	HTML task detail page

---

Services

Method	Path	Description
GET	/api/services	List bee-* systemd services and their states
POST	/api/services/action	start/stop/restart a service

---

Network

Method	Path	Description
GET	/api/network	List interfaces with state and IPv4 addresses
POST	/api/network/dhcp	Run dhclient on one or all interfaces
POST	/api/network/static	Set static IPv4 address
POST	/api/network/toggle	Bring interface up or down
POST	/api/network/confirm	Confirm pending network change (clears rollback)
POST	/api/network/rollback	Restore pre-change network snapshot

---

Export

Method	Path	Description
GET	/export/support.tar.gz	Download support bundle (live-generated)
GET	/export/file	Download a file from the export dir by path param
GET	/export/	Browse export dir (HTML index)
GET	/api/export/list	JSON list of files in export dir
GET	/api/export/usb	List removable USB targets available for export

---

GPU

Method	Path	Description
GET	/api/gpu/presence	{"nvidia", "amd", "nvidia_initializing", "amd_initializing": bool}. *_initializing = PCI GPU present but driver not up yet (distinct from absent). Backed by app.DetectGPUPresence.
GET	/api/gpu/nvidia	List NVIDIA GPUs from nvidia-smi
GET	/api/gpu/nvidia-status	Per-GPU status (ECC, power, throttle)
POST	/api/gpu/nvidia-reset	GPU reset by index
GET	/api/gpu/tools	nvidia-smi / rocm-smi tool availability

---

System

Method	Path	Description
GET	/api/system/ram-status	toram boot state and ISO copy status
POST	/api/system/install-to-ram	Copy ISO to RAM and verify active loop backing
GET	/api/system/time	Current host epoch, local wall-clock text, and timezone
POST	/api/system/time-sync	Set host time and timezone from the browser
POST	/api/system/reboot	Reboot the host
POST	/api/system/shutdown	Power off the host
GET	/api/install/disks	List block devices suitable for disk installation
POST	/api/install/run	Install bee to disk (background task)

---

Tools & NVMe

Method	Path	Description
GET	/api/tools/check	Check availability of required CLI tools
GET	/api/tools/nvme-formats	List NVMe format options for a device
POST	/api/tools/nvme-format/run	Run nvme-format on a device

---

Live metrics

Method	Path	Description
GET	/api/metrics/stream	SSE: live metrics (GPU power, temp, utilization)
GET	/api/metrics/latest	Latest metrics snapshot (JSON)
GET	/api/metrics/chart/	SVG chart for a metric over time
GET	/api/metrics/export.csv	Download metrics history as CSV

---

Blackbox logging

Method	Path	Description
GET	/api/blackbox/status	Blackbox log state (enabled, size, path)
POST	/api/blackbox/enable	Start recording blackbox log
POST	/api/blackbox/disable	Stop recording, flush to disk

---

UI pages

Method	Path	Description
GET	/	Main dashboard (serves all page routes)
GET	/viewer	Standalone JSON viewer for uploaded audit files

All pages are rendered server-side as HTML. The / route handles sub-paths such as /network, /services, /sat, /benchmark, /install, /validate, /export.