Node HTTP API

This page defines the wire protocol between Ithiltir-node and Dash, and the local endpoints provided by Local mode.

HTTP Endpoints

/api/node/* endpoints are served by Dash. Ithiltir-node calls them in Push mode; the node itself does not serve these paths.

Scope	Path	Method	Data	Success	Description
Local page	/	GET	HTML	200	Built-in single-node page
Local page	/local	GET	HTML	200	Alias of /
Local page	/metrics	GET	NodeReport	200	Returns 503 before first sample
Local page	/static	GET	Static	200	Returns 503 before static data is ready
Push target	/api/node/metrics	POST	NodeReport	200	Requires X-Node-Secret
Push target	/api/node/static	POST	Static	200	Requires X-Node-Secret; derived from target URL
Push target	/api/node/identity	POST	{}	200	Requires X-Node-Secret; returns install_id
Push debug local	/	GET	NodeReport	200	Enabled only by push --debug, bound to 127.0.0.1:<NODE_PORT or 9101>

Local GET routes also accept HEAD. Other methods return 405 with Allow: GET, HEAD.

Wire Rules

• JSON uses UTF-8.
• Timestamps are UTC RFC3339.
• Byte and packet counters are raw numeric counters.
• *Ratio fields are 0..1, not percentages.
• Arrays return [], not null.
• Optional fields without values are omitted.
• Runtime disk structure and static disk structure have different meanings. See Disk Metrics.

Dash receive boundaries:

• Bytes, capacities, counters, and uptime use non-negative signed 64-bit integers; process and connection counts use signed 32-bit integers.
• Static interval uses signed 32-bit range; CPU topology counts use signed 16-bit range.
• Out-of-range integers return 400 invalid_request; negative values or invalid ratios/rates return 422 invalid_metrics or 422 invalid_static_payload.
• Node version is limited to 64 characters; hostname and disk names to 255; disk ref to 320; disk kind/role and RAID health to 16; interface names to 64; filesystem type and logical health/level to 32.

Concurrent Push requests use Dash receive order for the current projection. An older receive that finishes later writes history only and cannot overwrite current metrics, frontend cache, or alert evaluation.

NodeReport

Top-level object:

{
  "version": "...",
  "hostname": "...",
  "timestamp": "...",
  "metrics": {}
}

Fields:

• version: node version.
• hostname: node hostname.
• timestamp: UTC RFC3339.
• metrics: Snapshot.

Snapshot

metrics fields:

• cpu: usage ratio, load, and CPU times.
• memory: memory and swap counters.
• disk: see Disk Metrics.
• network[]: interface counters and rates.
• system: liveness and uptime.
• processes: process count.
• connections: TCP and UDP counts.
• raid: RAID runtime state.
• thermal: thermal sensor runtime state.
• pressure: Linux PSI pressure runtime state.

Static

Top-level object:

{
  "version": "...",
  "timestamp": "...",
  "report_interval_seconds": 3,
  "cpu": {},
  "memory": {},
  "disk": {},
  "system": {},
  "raid": {}
}

Static reporting behavior:

• Static metadata has no outer wrapper object.
• report_interval_seconds is required.
• Static metadata is sent once at startup.
• Incomplete static collection keeps retrying until complete.
• After suppressed push failures recover, static metadata is sent again.