Skip to content
Yagra

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

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

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”

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}