Read a component's per-endpoint reachability
const url = 'https://example.com/api/v1/components/example/reachability';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/components/example/reachabilityComposes, per endpoint, the latest reachability verdict, the probe-layer signals that compose it, and the recent verdict transitions for the availability strip. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The component’s name, or a dotted address (e.g. boi.17c.415a.$comp.display-1)
The component’s name, or a dotted address (e.g. boi.17c.415a.$comp.display-1)
Responses
Section titled “ Responses ”OK
object
A URL to the JSON Schema for this object.
object
The probed address (target[:port]) from the endpoint params
The auth rung (the probe’s credential was accepted, or a held session’s login passed), present only when a credential was tried
object
When the verdict last changed: one is stored only on a transition, so an endpoint’s freshness is last_seen, not this
The latest stored verdict value (up/down)
The endpoint’s derived name (its transport)
The recent verdict transitions, oldest first, for the availability strip
object
The endpoint’s uuid, the address its custom methods take (POST /endpoints/{endpoint}:retry)
The friendly string an operator reads; absent when unset, and the row then reads the derived name verbatim
When the endpoint last delivered a batch, by the server’s clock and to within a few seconds, whatever it carried (any lane, any series, an unchanged value); absent until one lands
The per-layer probe signals that compose the verdict
object
The property_type key of the primary signal
A human timing detail (rtt / connect time), when present
The probe layer word (ping, port, or request: a udp endpoint’s request or an snmp endpoint’s get answered)
When the signal was observed
The latest signal value (1 = reachable/open, 0 = not)
The node that probes this endpoint
The gate a terminal refusal holds on the endpoint, its rung, class and reason, whether or not the endpoint holds a session (a reachability probe’s refusal gates it too); absent when none holds
object
The refusal’s class: auth, host-key, certificate or protocol
A refusal of a changed key only: the SHA256 fingerprint of the key the component offered instead. Trusting it is POST /endpoints/{endpoint}:retry with this exact value as host_key (a tls or https endpoint also takes it as certificate); while the refusal holds, any other value is refused (409)
A refusal of a changed key only (class host-key, or certificate for a pinned tls key): the SHA256 fingerprint of the key the endpoint pins, as the node refused against it. Present with offered_key or not at all
Why the gate holds (endpoint-rejection-reason): the class and the component’s own text (auth: the agent answered authorizationError for the community), scrubbed by the node of anything it sent. Published beside the gate by whatever the node was connecting with, its reachability probe, a poll or a held session, so an endpoint holding no session still says why it was refused. Absent when the node recorded none (a gate published before it did). Cut to 500 characters; the property’s series keeps the whole
The ladder rung the refusal holds: responsive for a host key, certificate or protocol refusal, authenticated for a credential. Nothing at or above it is attempted until the connection fingerprint moves
When the node last published the gate: a retry that lifts it and a refusal that sets it again each move it
The layer-7 responds rung (the protocol itself answered), when a probe has climbed it
object
When the verdict last changed: one is stored only on a transition, so an endpoint’s freshness is last_seen, not this
The latest stored verdict value (up/down)
The endpoint’s held session, while it is configured to hold one (a standing listen task, or a driver declaring a session): its latest state, when it changed, and why
object
Why the session is in its state (session-reason), the reason of its latest transition; a rejected session’s is its class and the component’s own text (auth: auth rejected), scrubbed by the node of anything it sent. Cut to 500 characters; the property’s series keeps the whole
The held session’s latest state (session-state): establishing, up, recovering, down, or rejected (a refusal retrying cannot fix; the node dials no more until the endpoint’s connection fingerprint moves)
When the session last changed state: a state is stored only on a transition, so a session is judged by the endpoint’s last_seen, not by this
A tls or https endpoint’s handshake and certificate: its verification mode, pinned key, handshake time, expiry and days left; absent on every other transport
object
Days from the latest probe to that not-after (tls-certificate-days-left), negative once expired: the number a threshold rule reads. Absent when expires is
The not-after of the certificate the latest probe accepted (tls-certificate-expiry); absent until one is accepted, and while a certificate gate holds (the probe then connects only, so the value would be the last accepted certificate’s, not the one offered now)
The latest probe’s handshake time in milliseconds (tls-handshake-time); absent until the component answers one
The public key the endpoint pins (tls-certificate), a SHA256 fingerprint; served in pin mode alone, and absent before first use
How the endpoint’s connections judge the certificate (its driver’s tls-mode input, verify when none is set): verify (against the node’s system roots, the server name the host), pin (the public key trusted on first use, any other refused) or skip (nothing checked, the operator’s explicit choice)
The transport (icmp, tcp, …)
The latest reachability verdict, or null if none yet
object
When the verdict last changed: one is stored only on a transition, so an endpoint’s freshness is last_seen, not this
The latest stored verdict value (up/down)
Example
{ "$schema": "/api/v1/schemas/ReachabilityOutputBody.json", "endpoints": [ { "rejection": { "rung": "reachable" }, "session": { "state": "establishing" } } ]}default
Section titled “default ”Error
object
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
object
Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{ "$schema": "/api/v1/schemas/ErrorModel.json", "detail": "Property foo is required but is missing.", "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "about:blank"}