Retrieve all network nodes including appliances and agents with filtering options

Request

List both appliances and agents. The fields config and shadow will be empty unless specified in the projection parameter. The query for the config or shadow must be at least one level deep - projection[0][0]=config won't work, but projection[0][0]=config&projection[0][1]=gateway will result in config.gateway being populated.

Requires nodes::read permission.

Security

JWTAuthorizer

Query

clusterstring

When provided, limit the nodes to members of the cluster. Should be the full cluster FQDN, e.g., mycluster.trustgrid.io.

tagsstring

Comma-separated key:value pairs for tag filtering, e.g., location:Austin,device:Trustgrid.

projection[]Array of any

Reduces the response to a smaller set of fields. When omitted, all fields are returned (name, fqdn, online, cluster, lastip, last_connect, created_at, device, location, heartbeat, lifecycleState, disconnectTime, orderID, plus base fields).

When specified, the response contains only a fixed base set plus each explicitly requested field.

Base set (always present when any projection is specified): uid, state, type, tags, tgTags, tgrn, keys. Top-level requestable fields: name, fqdn, online, cluster, lastip, last_connect, created_at, device, location, heartbeat, lifecycleState, disconnectTime, orderID

IMPORTANT: shadow and config cannot be used as flat projection keys (e.g., projection[]=shadow or projection[]=config are rejected as too large). To retrieve data from these objects, you must use nested indexed projection (see below).

WARNING: Dot-notation strings do NOT work. projection[]=config.gateway.enabled silently returns an empty config: {} object. Do not use dot notation.

Nested projection uses indexed bracket notation where each projection entry has an outer index N and each path segment has an inner index M. To request config.gateway.enabled as entry 0 and shadow.reported["node-core.version"] as entry 1: projection[0][0]=config&projection[0][1]=gateway&projection[0][2]=enabled&projection[1][0]=shadow&projection[1][1]=reported&projection[1][2]=node-core.version

If using curl, use the -g flag to prevent brace expansion.

curl -i -X GET \
  'https://apidocs.trustgrid.io/_mock/node?cluster=string&tags=string&projection%5B%5D=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json

Array [

clusterstring

Cluster FQDN

Example:"mycluster.trustgrid.io"

configobject

Node configuration. Each sub-key mirrors an individual PUT /node/{nodeID}/config/* endpoint. In direct single-node responses, this object contains the complete configuration. In list responses, config may be included when explicitly requested via projection; when returned that way, only the projected config fields are present.

namestring

Node name

Example:"mynode"

onlineboolean

True when the node is connected to the control plane

shadowobject

AWS IoT Device Shadow — the node's desired and reported state store. reported is a flat key-value map updated by the node itself; desired holds pending configuration the node has not yet acknowledged (usually empty). Most fields in reported use dot-notation keys. Common reported keys: node-core.version (software version), memory (RAM in MB), storage (disk free in GB), cores (CPU count), dnsResolution ("healthy"/"unhealthy"), repoConnectivity ("true"/"false"), os.distro.id (e.g., "ubuntu"), ssh.local ("true"/"false"), profile.name, node.upgrade.state, features (object of enabled feature flags), nic.{name}.mac/mtu/speed/dhcp (NIC telemetry).

statestring

Node state

Enum:"ACTIVE""INACTIVE"

tagsobject

User-defined tags for organizing and filtering nodes

typestring

Device type

Enum:"Agent""Node"

uidstring

Node ID

Example:"19084f81-5668-41ee-adbe-295e4c65531a"

fqdnstring

Fully qualified domain name, e.g., mynode.myorg.trustgrid.io. Omitted when projection[] is used without this field.

Example:"mynode.myorg.trustgrid.io"

lastipstring

Last IP address observed when the node connected. Omitted when projection[] is used without this field.

Example:"203.0.113.42"

last_connectinteger

Unix timestamp in milliseconds of the most recent control plane connection. Omitted when projection[] is used without this field.

orgstring

Organization ID (UUID) that owns this node. Returned only by GET /node/{nodeID}.

Example:"aad89024-5927-4ebd-97e2-3cc605c1da5f"

domainstring

Domain FQDN this node belongs to. Returned only by GET /node/{nodeID}.

Example:"myorg.trustgrid.io"

tgTagsobject

System-managed tags assigned by the Trustgrid platform. Read-only; always returned in list and single-node responses.

keysobject

Named cryptographic public keys used for node authentication and WireGuard tunneling. Keyed by purpose (e.g. wireguard, identity); values are opaque string-encoded public keys. Always returned but rarely needed directly.

tgrnstring

Trustgrid Resource Name — a globally unique identifier for this node across the platform. Format: tgrn:tg::nodes:node/{uid}. Always returned.

Example:"tgrn:tg::nodes:node/19084f81-5668-41ee-adbe-295e4c65531a"

created_atinteger

Unix timestamp (seconds) when the node was registered. Omitted when projection[] is used without this field.

deviceobject

Hardware device information detected from the physical or virtual appliance. Omitted when projection[] is used without this field.

locationobject

IP geolocation derived from the node's last observed IP address. Omitted when projection[] is used without this field.

heartbeatobject

Most recent heartbeat received from the node's control plane connection. Omitted when projection[] is used without this field.

lifecycleStatestring

Operational lifecycle state of the node. Omitted when projection[] is used without this field.

Enum:"pre-production""production""maintenance""decommissioned"

disconnectTimeinteger

Unix timestamp (seconds) when the node last disconnected from the control plane. Omitted when projection[] is used without this field.

orderIDstring

UUID of the hardware provisioning order associated with this node. Omitted when projection[] is used without this field.

]

Response

[
  {
    "cluster": "mycluster.trustgrid.io",
    "config": { … },
    "name": "mynode",
    "online": true,
    "shadow": { … },
    "state": "ACTIVE",
    "tags": { … },
    "type": "Agent",
    "uid": "19084f81-5668-41ee-adbe-295e4c65531a",
    "fqdn": "mynode.myorg.trustgrid.io",
    "lastip": "203.0.113.42",
    "last_connect": 0,
    "org": "aad89024-5927-4ebd-97e2-3cc605c1da5f",
    "domain": "myorg.trustgrid.io",
    "tgTags": { … },
    "keys": { … },
    "tgrn": "tgrn:tg::nodes:node/19084f81-5668-41ee-adbe-295e4c65531a",
    "created_at": 0,
    "device": { … },
    "location": { … },
    "heartbeat": { … },
    "lifecycleState": "pre-production",
    "disconnectTime": 0,
    "orderID": "string"
  }
]