The dependency graph: every node with its parent edge, current state, and any active root-cause attribution. Admin-only data source.

GET

/api/v1/topology

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

The default page is large — the graph views assemble the whole fleet, so fewer round-trips is better — but bounded, so no single response is a multi-MB blob.

Authorizations

• bearer

Parameters

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

200

One keyset page of the dependency graph; next_cursor is null on the last page

Media typeapplication/json

One keyset page of the dependency graph.

object

next_cursor

Pass back as cursor for the next page; null ⇒ this was the last one.

string | null

nodes

required

Array<object>

One node in the dependency/topology graph.

object

id

required

string format: uuid

name

required

string

parent_id

Upstream parent in the dependency graph (null ⇒ a root).

string | null format: uuid

root_cause

Upstream node currently identified as the root cause of this node’s alert (dependency suppression), if any — lets a client collapse downstream alerts under the cause.

string | null format: uuid

state

required

The current state of a monitored node or check.

string

Allowed values: ok warning critical unknown unreachable maintenance

Example

{
  "nodes": [
    {
      "state": "ok"
    }
  ]
}

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"
  }
}

503

Skeleton mode has no inventory to build the graph from

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"
  }
}