GET
/api/peersList peers
Lists peers, optionally filtered by name, IP address, or network-interface MAC address. Use name, ip, and mac to narrow the returned peer collection; you can supply each filter independently.
namestringoptional
Filter peers by name.
ipstringoptional
Filter peers by IP address.
macstringoptional
Filter peers by the MAC address of a network interface.
200Returns a JSON array of peer objects, including each peer's accessible peer count and creation timestamp.
idstringrequired
Peer ID
namestringrequired
Peer's hostname
approval_requiredbooleanrequired
(Cloud only) Indicates whether peer needs approval
city_namestringrequired
Commonly used English name of the city
connectedbooleanrequired
Peer to Management connection status
connection_ipstringrequired
Peer's public connection IP address
country_codestringrequired
2-letter ISO 3166-1 alpha-2 code that represents the country
created_atstringrequired
Peer creation date (UTC)
disapproval_reasonstringoptional
(Cloud only) Reason why the peer requires approval
dns_labelstringrequired
Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
ephemeralbooleanrequired
Indicates whether the peer is ephemeral or not
extra_dns_labelsarray<string>required
Extra DNS labels added to the peer
geoname_idintegerrequired
Unique identifier from the GeoNames database for a specific geographical location.
groupsarray<object>required
Groups that the peer belongs to
hostnamestringrequired
Hostname of the machine
inactivity_expiration_enabledbooleanrequired
Indicates whether peer inactivity expiration has been enabled or not
ipstringrequired
Peer's IP address
ipv6stringoptional
Peer's IPv6 overlay address
kernel_versionstringrequired
Peer's operating system kernel version
last_loginstringrequired
Last time this peer performed log in (authentication). E.g., user authenticated.
last_seenstringrequired
Last time peer connected to Netbird's management service
local_flagsobjectoptional
login_expiration_enabledbooleanrequired
Indicates whether peer login expiration has been enabled or not
login_expiredbooleanrequired
Indicates whether peer's login expired or not
network_addressesarray<object>optional
Network interfaces (IP + MAC) reported by the peer
osstringrequired
Peer's operating system and version
serial_numberstringrequired
System serial number
ssh_enabledbooleanrequired
Indicates whether SSH server is enabled on this peer
ui_versionstringrequired
Peer's desktop UI version
user_idstringrequired
User ID of the user that enrolled this peer
versionstringrequired
Peer's daemon or cli version
accessible_peers_countintegerrequired
Number of accessible peers
400Returned when the request is invalid.
401Returned when authentication is required but the request is unauthenticated.
403Returned when access to the requested peers is forbidden.
500Returned when an internal server error occurs.
Error handling
A 400 is returned for a bad request; a 401 when authentication is required but not provided; a 403 when access is forbidden; and a 500 when an internal server error occurs. Use name, ip, and mac to filter peers by their name, IP address, and network-interface MAC address.