get_node

GET

/api/v1/nodes/{node_id}

curl --request GET \
  --url https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Responses

200

The node’s configuration, bindings and resolved kind

Media typeapplication/json

One node’s configuration detail, including its bindings (profile/credential/parent) so the node-detail page can show and edit them. Live mode only (PostgreSQL inventory).

object

address

required

string

credential_id

string | null format: uuid

dns_check

One of:

null

null

object

DNS-monitor config when this node carries a dns_checks row; null otherwise.

object

max_depth

Maximum CNAME hops before giving up (default 8).

integer format: int32

name

required

The name to resolve, e.g. horryworks.net. Stored normalized (lowercase, no trailing dot).

string

record_type

Which record type the chain must reach (default A).

string

Allowed values: A AAAA CNAME

resolver

Recursive resolver to query. None ⇒ the poller container’s system resolver.

string | null

resolver_port

Resolver port (default 53).

integer format: int32

timeout_ms

Total budget for the whole chain walk, in milliseconds (default 3000).

integer format: int32

group_id

The group this node belongs to; 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 — the kind the scheduler actually polls it as, resolved by the one precedence in [NodeKind::resolve].

The three configs below are the raw rows, and a node is not guaranteed to carry only one: the API edge refuses a second, but rows predating that guard exist. Reading the configs and concluding a kind from whichever is non-null is how the node page came to show a URL-monitor health card for a node the poller was treating as a Meraki device. Branch on this instead.

string

Allowed values: meraki url dns device

meraki_device

One of:

null

null

object

Cisco Meraki binding when this node carries a meraki_devices row; null otherwise.

object

model

Device model (e.g. “MX67”) — display only.

string | null

network_id

required

The Meraki networkId the device belongs to.

string

org_id

required

The Meraki organizationId (the API path segment) — denormalised for display.

string

org_uuid

required

Internal handle of the owning meraki_orgs row.

string format: uuid

product_type

required

Meraki productType (appliance/switch/wireless/…).

string

serial

required

The device serial — the join key returned by the org-bulk endpoints.

string

model

string | null

name

required

string

parent_id

string | null format: uuid

pool

The node’s own poll-pool (ADR-009/020); null ⇒ it inherits from its folder, else the default pool. Deliberately the raw stored value, not the effective one, so the edit form can tell an explicit assignment from an inherited one — the effective pool (and which poller currently holds the node) comes from GET /nodes/:id/assignment.

string | null

profile_id

string | null format: uuid

url_check

One of:

null

null

object

URL-monitor config when this node carries a url_checks row; null otherwise.

object

body_match

One of:

null

null

object

Optional keyword rule applied to the response body.

object

mode

Whether the keyword must be present or absent (default: present).

string

Allowed values: contains not_contains

pattern

required

The keyword to look for. Matched as plain, case-sensitive text — not a regular expression.

string

body_max_bytes

How many bytes of the response body to read (default 65536, range 1024–1048576). Applies to both body_match and json_extract; the body is not read at all unless one of them is set.

integer format: int32

credential

One of:

null

null

string

Optional auth credential (Basic/Bearer/custom header). A reference only — core resolves it to an [HttpAuth] and inlines that into the poll job, the same path SNMP credentials take.

string format: uuid

expected_status

One of:

object

Any 2xx (the default).

object

kind

required

string

Allowed values: two_xx

object

An explicit set of acceptable codes.

object

codes

required

Array<integer>

kind

required

string

Allowed values: exact

object

An inclusive range [lo, hi].

object

hi

required

integer format: int32

kind

required

string

Allowed values: range

lo

required

integer format: int32

follow_redirects

Follow 3xx redirects (default true).

boolean

json_extract

Values to lift out of a JSON response body and record as operator-named metrics.

Each rule adds one gauge per poll. A rule whose path is missing, or whose value is not a number, records nothing for that poll rather than a zero.

Array<object>

One number to lift out of a JSON response body and record as a metric.

object

metric

required

The metric name to record the value under, e.g. queue_depth. Must match [A-Za-z_:][A-Za-z0-9_:]* and must not be one of the names the monitor already emits.

string

path

required

Dot-separated path to the value, e.g. data.queue.depth or items.0.value. Array elements are indexed by number; items[0].value is accepted and means the same thing.

Not a JSONPath expression: the path names exactly one location, so the rule always produces either one number or nothing.

string

method

Request method (default GET).

string

Allowed values: GET HEAD POST

timeout_ms

Per-request timeout, in milliseconds (default 5000).

integer format: int32

url

required

Full URL to probe, e.g. https://api.example.com/health.

string

verify_tls

Verify the TLS certificate chain (default true; never silently disabled — security.md).

boolean

vendor

Descriptive maker/model, editable from the node detail.

string | null

Example

{
  "dns_check": {
    "record_type": "A"
  },
  "kind": "meraki",
  "url_check": {
    "body_match": {
      "mode": "contains"
    },
    "expected_status": {
      "kind": "two_xx"
    },
    "method": "GET"
  }
}

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

Example^generated

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

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

Example^generated

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

404

No such node, or this deployment has no inventory

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

Example^generated

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