Skip to content
Yagra

list_nodes

GET
/api/v1/nodes
curl --request GET \
  --url https://example.com/api/v1/nodes \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
cursor
string format: uuid
limit
integer format: int64
search
string

Case-insensitive substring of the node’s name or address.

address
string

Exact IP address of the node, compared as an address (so 2001:DB8::1 finds 2001:db8::1). Pair it with kind=device,meraki to ask whether a device is already monitored at an address. A value that is not an IP address is rejected.

state
string

Comma-separated display states (ok | warning | critical | unknown | unreachable | maintenance); empty or absent means every state. An unknown token is rejected rather than ignored.

kind
string

Comma-separated monitoring kinds (wireless_ap | meraki | url | dns | device); empty or absent means every kind.

pool
string

Comma-separated effective poll pools — a node’s own pool when it sets one, otherwise the nearest folder ancestor that does, otherwise the default pool. Filtering on the stored column alone would miss every node that inherits, which is most of them. Pools are named by the operator, so there is no vocabulary to reject against: an unknown name simply matches nothing.

Responses

Section titled “Responses”

200

Section titled “200”

One keyset page of the inventory, or a single capped page in search mode

Media typeapplication/json

One keyset page of the inventory.

object
next_cursor

Pass back as cursor for the next page; null ⇒ this was the last one. Always null in filter mode, which returns a single capped page by design.

string | null
nodes
required
Array<object>

One inventory row (mirrors the WebUI NodeSummary).

object
address
required

The node’s address. 0.0.0.0 (or ::) means the node has none — a Meraki device the Dashboard reports no LAN IP for, such as a mesh repeater (ADR-175). The column cannot be empty, so that is how “no address” is stored; it is not an address anything can reach.

string
group_id

The group this node belongs to (for the inventory tree); null ⇒ ungrouped.

string | null format: uuid
id
required

Stable identifier for a monitored node.

A UUID, not a name or address — both of which can change over a node’s life.

string format: uuid
kind
required

What this node is, and therefore how it is polled — the value that distinguishes a URL or DNS monitor from an ordinary ICMP/SNMP device in the inventory.

Resolved by NodeKind::resolve, the same function GET /nodes/{id} and the scheduler ask, so a list row can never disagree with the detail page it opens.

string
Allowed values: wireless_ap meraki url dns device
meraki_product_type

A Meraki node’s product type as the Dashboard names it — wireless (an MR access point), switch, appliance, … — and absent on every other node. What the list’s “AP” badge is read from (ADR-168 decision 11): an MR stays kind: meraki, so the kind alone cannot say it is an access point. The detail page reads the same value from meraki_device.product_type.

string | null
meraki_repeater

true on a Meraki access point that is a mesh repeater: it has no wired uplink, so the Dashboard reports no LAN IP for it and its address is 0.0.0.0 (ADR-175). Absent otherwise. What the list’s “Repeater” badge is read from.

boolean
model
string | null
name
required
string
pool

The node’s own poll-pool; null ⇒ inherited from its folder, else the default pool. The tree’s pool picker edits exactly this value, so it is what marks the active choice — the effective pool (and the poller holding the node) comes from /nodes/:id/assignment.

string | null
sort_order
required

Manual order within the group (the tree sorts members by this, then by name).

number format: double
state
required

The current state of a monitored node or check.

string
Allowed values: ok warning critical unknown unreachable maintenance
vendor

Descriptive maker/model for the “name (addr) (vendor) (model)” display.

string | null
truncated
required

Filter mode only: matches exist that this answer does not contain, because the page hit its cap or the candidate scan hit its ceiling. Always false while paging.

A separate field rather than something the client infers from nodes.len(), because once the server rejects candidates after the query those two stop meaning the same thing: a filter that scans 5,000 rows and keeps 3 returns three rows and is still incomplete.

boolean
Example
{
  "nodes": [
    {
      "kind": "wireless_ap",
      "state": "ok"
    }
  ]
}

400

Section titled “400”

An unknown state or kind token, or an address that is not an IP address

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks the View permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

Too many inventory reads in flight — retry shortly (list_busy)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}