REST API Reference
Explore NetIntel's deterministic operational outputs: telemetry, derived features, health assessments, recommendations, and diagnostic findings.
Base URL and endpoints
The default API listener is loopback at 127.0.0.1:8080. Use the host and port configured for your deployment. For remote access, apply suitable network controls and TLS termination.
BASE_URL="http://127.0.0.1:8080"
curl -sS "$BASE_URL/api/v1/health"| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/health | Service status, name, version |
| GET | /api/v1/telemetry | System measurements |
| GET | /api/v1/features | Derived operational indicators |
| GET | /api/v1/assessments | Component and overall health |
| GET | /api/v1/recommendations | Current recommendations |
| GET | /api/v1/diagnostics | Diagnostic status and findings |
Health
curl -sS "$BASE_URL/api/v1/health"{"status":"ok","name":"NetIntel","version":"1.0.0"}Telemetry
Returned under system. Fields include cpu (usage, logicalCores, state), memory (total/available/used bytes, used percentage, state), uptime, load, thermal, mounts, and interfaces. Thermal entries include zone name, type, and temperature; mount entries include device, mount point, filesystem, capacity and usage; interface entries include receive/transmit bytes, packets, errors, and drops. The group state fields are thermalState, mountsState, and networkState. Large JSON numeric counters may not retain exact integer precision in every consumer runtime.
Derived features
The features object exposes cpuStress, memoryPressure, filesystemPressure, numeric thermalState, loadCoreRatio, resourceSaturation, and networkActivity. Each has a corresponding state field: cpuStressState, memoryPressureState, filesystemPressureState, thermalFeatureState, loadCoreRatioState, resourceSaturationState, and networkActivityState.
thermalState is numeric in this endpoint, but a string state field in telemetry.Assessments
{"assessments":{"cpu":"Healthy","memory":"Healthy","filesystem":"Warning","thermal":"Healthy","loadCore":"Healthy","resourceSaturation":"Warning","network":"Unavailable","overall":"Warning"}Keys: cpu, memory, filesystem, thermal, loadCore, resourceSaturation, network, overall. Values include Unavailable, NotReady, Healthy, Warning, and Critical.
Recommendations
Each item contains severity, title, and message.
{"recommendations":[{"severity":"Advisory","title":"Low Filesystem Capacity","message":"Filesystem usage is approaching capacity. Review disk usage and plan cleanup before storage becomes exhausted."}]}Recommendation severities: Info, Advisory, Action, Immediate. Internal recommendation IDs are not exposed in this response.
Diagnostics
Top-level fields are status (Pending or Complete) and findings, which may be empty. Each finding contains severity, title, description, recommendation, and an evidence object of string key/value pairs.
{"status":"Complete","findings":[{"severity":"Advisory","title":"High CPU Utilization","description":"Top CPU consuming processes detected.","recommendation":"HighCpuUtilization","evidence":{"Process":"example-worker","CPU":"74.9%","Samples":"5"}}]}Diagnostic severity values: Info, Advisory, Warning, Critical. Empty findings mean no findings were returned in that response; they do not prove every provider ran or that a root cause was ruled out.
States, errors, and operational context
- Telemetry/feature states:
Unavailable,NotReady,Valid - Assessment levels:
Unavailable,NotReady,Healthy,Warning,Critical - Recommendation severity:
Info,Advisory,Action,Immediate - Diagnostic severity:
Info,Advisory,Warning,Critical
Successful serialization returns HTTP 200. A serialization failure that produces an empty result returns HTTP 500 with {"error":"Internal server error"}. Telemetry provides measurements; features provide derived indicators; assessments describe health; recommendations suggest next steps; diagnostics provide findings where available. These deterministic outputs can support external AI workflows. NetIntel itself is not an AI model.