API Reference

The REST API gives you programmatic access to the same data as the Stealthium dashboard: security alerts, your GPU fleet, and fleet-wide metrics. All endpoints live under https://api.stealthium.online/api/v1, require a bearer token, and return JSON. Everything is read-only except updating an alert's state.

Conventions

Errors. Every non-2xx response has the same body:

{ "error": "invalid_query", "message": "unknown filter field: severty" }

error	Status	Meaning
unauthorized	401	Missing or invalid bearer token.
invalid_query	400	Bad filter field/operator, sort field, id, limit, or timestamp.
invalid_cursor	400	Malformed pagination cursor.
not_found	404	The resource (e.g. alert id) doesn't exist.
upstream_error	502	A backing service failed — retry later.
internal_server_error	500	Unexpected server failure.

Scoping. Every list endpoint accepts optional numeric scope filters as query parameters: customer_id, workspace_id, api_key_id. Omit them to see everything your account can access.

Timestamps are RFC 3339 UTC strings, e.g. 2026-07-24T09:14:03Z.

---

Alerts

List alerts

GET /api/v1/alerts/

Returns alerts, newest first by default.

Parameter	Description
filter[<field>][<op>]	Filter on a field — see Filtering below. Combine filters on different fields; they AND together.
sort	Sort field: timestamp (default), severity, type, state, hostname. Prefix with - for descending (default: -timestamp). Sorting by severity orders from critical down, not alphabetically.
limit	Page size. Default 1000, max 10000.
cursor	Opaque cursor from a previous response's next_cursor.
from, to	Only alerts within this time range (RFC 3339).
customer_id, workspace_id, api_key_id	Scope filters.

curl -G "https://api.stealthium.online/api/v1/alerts/" \
  --data-urlencode "filter[severity][in]=critical,high" \
  --data-urlencode "limit=100" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "alerts": [
    {
      "id": "0b6ec7a4-52f7-4f7e-9df1-8f6f3f2b7c1d",
      "title": "Unknown binary executed",
      "description": "A binary not seen before on this host was executed.",
      "type": "unknown_binary_exec",
      "severity": "high",
      "state": "active",
      "created_at": "2026-07-24T09:14:03Z",
      "hostname": "gpu-node-17",
      "gpu_model": "NVIDIA H100 80GB HBM3",
      "gpu_serial": "1650923000000",
      "workspace_id": 3,
      "api_key_id": 12
    }
  ],
  "next_cursor": "eyJ2IjoiMjAyNi0wNy0yNFQwOToxNDowM1oi...",
  "total": 148
}

hostname, gpu_model, gpu_serial, workspace_id, and api_key_id are null when not applicable to the alert.

Filtering

Filters use the form filter[<field>][<op>]=<value>. The operators depend on the field type:

Fields	Operators	Notes
severity, type, state	in, notIn, equals, notEquals	in/notIn take a comma-separated list.
hostname, title, description	contains, notContains, startsWith, endsWith, equals, notEquals	Free text.
timestamp	gte, lte, between	RFC 3339 values; between takes <from>,<to>.

Valid values: severity is one of critical, high, medium, low, info; state is active or ignored.

All type values

cpu_usage, gpu_usage, gpu_firmware, gpu_shader, gpu_dma, gpu_power, gpu_interrupt, gpu_command, gpu_memory, gpu_ransomware, gpu_texture, gpu_pcie, gpu_thermal, gpu_throttle, gpu_ecc, process_anomaly, privilege_escalation, command_line_anomaly, system_info_change, network_anomaly, cpu_anomaly, kernel_oops, container_sensitive_mount, container_gpu_access, container_privileged, container_escape, container_cgroup_escape, unknown_binary_exec, rogue_ebpf, gpu_driver_access, c2_covert_channel, model_poisoning, controlplane_integrity, controlplane_credential_attack, vm_escape, ray_job_rce

Pagination

Pagination is cursor-based. While next_cursor is non-null, pass it back as cursor to get the next page — pages never overlap or skip alerts. total is computed only on the first page (a request without a cursor) and is null on later pages.

Alert facet counts

GET /api/v1/alerts/facets

Per-value alert counts for severity, type, and state — useful for building filter UIs. Accepts the same filter, time-range, and scope parameters as List alerts. Each column's counts ignore any filter on that same column, so selecting severity=high doesn't zero out the other severity buckets.

curl -G "https://api.stealthium.online/api/v1/alerts/facets" \
  --data-urlencode "filter[state][equals]=active" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "severity": [
    { "value": "high", "count": 12 },
    { "value": "medium", "count": 30 }
  ],
  "type": [
    { "value": "gpu_memory", "count": 18 },
    { "value": "process_anomaly", "count": 24 }
  ],
  "state": [
    { "value": "active", "count": 42 },
    { "value": "ignored", "count": 7 }
  ]
}

Get alert details

GET /api/v1/alerts/{id}/info

Full detail for one alert. {id} is the alert UUID from List alerts. On top of the list fields it adds workspace_name and customer_id, plus resource_details — detail maps whose contents depend on the alert type (null means no data for this alert). summary_data and correlated_alerts are reserved for future use and currently empty.

curl "https://api.stealthium.online/api/v1/alerts/0b6ec7a4-52f7-4f7e-9df1-8f6f3f2b7c1d/info" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "alert": {
    "alert": {
      "id": "0b6ec7a4-52f7-4f7e-9df1-8f6f3f2b7c1d",
      "title": "Unknown binary executed",
      "description": "A binary not seen before on this host was executed.",
      "type": "unknown_binary_exec",
      "severity": "high",
      "state": "active",
      "created_at": "2026-07-24T09:14:03Z",
      "hostname": "gpu-node-17",
      "workspace_id": 3,
      "workspace_name": "production",
      "customer_id": 1,
      "api_key_id": 12
    },
    "summary_data": {},
    "resource_details": {
      "process_details": { "pid": 41233, "process_name": "python3" },
      "memory_details": null,
      "workload_details": null,
      "gpu_details": { "device_name": "NVIDIA H100 80GB HBM3" },
      "node_details": { "hostname": "gpu-node-17" },
      "container_details": null
    },
    "correlated_alerts": {}
  }
}

Get alert timeline

GET /api/v1/alerts/{id}/timeline

The process-level events recorded around the alert, oldest first.

curl "https://api.stealthium.online/api/v1/alerts/0b6ec7a4-52f7-4f7e-9df1-8f6f3f2b7c1d/timeline" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "timeline_events": [
    {
      "ts": "2026-07-24T09:13:58Z",
      "pid": 41233,
      "tid": 41233,
      "event_type": "process_exec",
      "event_info": "process started",
      "comm": "python3",
      "command_line": "python3 train.py --epochs 10",
      "args": ["--epochs", "10"],
      "pwd": "/home/ml/jobs"
    }
  ]
}

Update alert state

PUT /api/v1/alerts/{id}/state

Sets an alert's state to active or ignored. This is the only write operation in the API.

curl -X PUT "https://api.stealthium.online/api/v1/alerts/0b6ec7a4-52f7-4f7e-9df1-8f6f3f2b7c1d/state" \
  -H "Authorization: Bearer <YOUR-JWT>" \
  -H "Content-Type: application/json" \
  -d '{"state": "ignored"}'

Response:

{ "message": "alert state updated" }

---

GPUs

List GPUs

GET /api/v1/gpus

Every GPU in your fleet with its identity, health, and freshest telemetry. Accepts the scope parameters (customer_id, workspace_id, api_key_id).

curl "https://api.stealthium.online/api/v1/gpus" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "gpus": [
    {
      "gpuId": "GPU-8f2c1a7e-1d2b-4c3d-9e8f-0a1b2c3d4e5f",
      "vendor": "NVIDIA",
      "model": "H100 80GB HBM3",
      "health": "healthy",
      "hostname": "gpu-node-17",
      "pcieAddress": "0001:00:00.0",
      "serialNo": "1650923000000",
      "utilizationPct": 87.5,
      "temperatureC": 64,
      "lastSeen": "2026-07-24T09:14:03Z"
    }
  ]
}

health is healthy, degraded, or critical. utilizationPct and temperatureC are null when no recent telemetry exists.

Get GPU details

GET /api/v1/gpus/{id}

Full detail for one GPU. {id} is the gpuId (GPU-…) or the PCIe address from the list. The response groups everything the dashboard shows:

Section	Contents
specs	Serial number, compute stack, driver/firmware versions, hostname, PCIe address, MIG state.
security, securityDiagnostics	Alert counts for the last 24h/7d, per-severity breakdowns, recent XID error rows.
xid	XID error count (24h), 7-day trend (rising/flat/falling), last error code.
telemetry	Live utilization, memory, temperature, power, fan — each with a history series for sparklines.
processes	Processes currently using the GPU, with per-process utilization and memory.
utilization	Busy/idle breakdown, usage categories, analyzed-event counts, process families.

Fields with no data are returned empty or null rather than omitted, so the response shape is stable.

curl "https://api.stealthium.online/api/v1/gpus/GPU-8f2c1a7e-1d2b-4c3d-9e8f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "gpu": {
    "gpuId": "GPU-8f2c1a7e-1d2b-4c3d-9e8f-0a1b2c3d4e5f",
    "vendor": "NVIDIA",
    "model": "H100 80GB HBM3",
    "health": "healthy",
    "specs": {
      "serialNo": "1650923000000",
      "computeStack": "CUDA 12.4",
      "driverVersion": "550.54.15",
      "firmwareVersion": "96.00.74.00.01",
      "hostname": "gpu-node-17",
      "pcieAddress": "0001:00:00.0",
      "migEnabled": false
    },
    "security": { "totalAlerts24h": 2, "alertsBySeverity": [1, 1, 0] },
    "xid": { "errors24h": 0, "trend7d": "flat", "lastCode": null },
    "telemetry": {
      "utilizationPct": 87.5,
      "memoryUsedGb": 42.1,
      "memoryTotalGb": 80,
      "temperatureC": 64,
      "powerDrawW": 512,
      "powerLimitW": 700,
      "fanPct": 55,
      "history": {
        "utilization": [81, 85, 87.5],
        "memory": [40.2, 41.8, 42.1],
        "temperature": [62, 63, 64],
        "power": [498, 505, 512]
      }
    },
    "processes": [
      {
        "pid": "41233",
        "name": "python3",
        "jobType": "training",
        "description": "ML training job",
        "usageCategory": "compute",
        "gpuUtilizationPct": 85,
        "memoryUsageGb": 38.4,
        "startedAt": "2026-07-24T06:02:11Z"
      }
    ],
    "lastRefreshedAt": "2026-07-24T09:14:03Z"
  }
}

---

Metrics

Get fleet metrics

GET /api/v1/metrics

Fleet-wide metrics: alert counts with histograms, top alert types, live asset counts, and aggregated telemetry — the same numbers the dashboard shows.

Parameter	Description
from, to	Time window for the alert counts and histograms (RFC 3339).
customer_id, workspace_id, api_key_id	Scope filters.

curl "https://api.stealthium.online/api/v1/metrics?from=2026-07-17T00:00:00Z&to=2026-07-24T00:00:00Z" \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "metrics": {
    "alerts_by_severity": [
      {
        "label": "critical",
        "value": 2,
        "data": [{ "date": "Jul 23", "value": 1 }]
      }
    ],
    "top_alert_types": [
      { "icon": "gpu_memory", "title": "gpu_memory", "count": 18 }
    ],
    "asset_coverage": [{ "label": "gpus", "count": 24, "data": [] }],
    "metrics_summary": {
      "gpu_count": 24,
      "avg_gpu_utilization": 71.4,
      "avg_gpu_temperature": 63.2,
      "total_xid_errors": 3,
      "container_count": 112,
      "vm_count": 4
    },
    "metrics_charts": {}
  }
}

metrics_summary aggregates live telemetry across the fleet. Its keys, grouped by domain:

Domain	Keys
GPU fleet	gpu_count, avg_gpu_utilization, avg_gpu_temperature, avg_gpu_power, avg_gpu_memory, avg_gpu_fan_speed, avg_clock_speed, avg_memory_clock
GPU health	avg_health_score, avg_thermal_slope, total_ecc_errors, total_xid_errors, active_crash_chains, total_throttle_events
CPU & processes	avg_cpu_load, avg_cpu_utilization, process_count, avg_fork_rate, avg_exit_rate
Containers & VMs	container_count, gpu_container_count, mps_container_count, container_process_count, vm_count

Averages (avg_*) are across the live fleet; totals (total_*, *_count) are sums. Additional keys (chart data, metrics_charts) may appear in the payload — treat anything not listed above as unstable.