list_alerts

GET

/api/v1/alerts

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

Authorizations

• bearer

Responses

200

Every active alert, each decorated with its inbound ack state

Media typeapplication/json

Array

An active alert plus its inbound (read-only) ack state.

subject_kind and subject_name decompose the alert’s node field, which carries either a node’s UUID or pool:<name>. The live alert stream emits the same three keys.

object

at_unix_ms

required

When it fired (Unix ms, UTC).

integer format: int64

breach

One of:

null

null

object

Numeric breach detail for a threshold alert; None for a liveness alert.

object

direction

required

Which way the metric crossed its bound.

string

Allowed values: above below

threshold

The bound crossed for the committed severity, if the rule defines one at that level.

number | null format: double

value

required

Observed sample value that committed the transition.

number format: double

check

required

The check that produced it.

string format: uuid

flapping

required

Whether the underlying check is currently flapping.

boolean

metric

required

Metric the check measured (e.g. "icmp_rtt_ms"; the liveness sentinel for up/down). Carried for the history log + notification payload so a human can read what fired — not part of alert identity (dedup/grouping ignore it).

string

node

required

What the alert is about: a node’s UUID, or pool:<name> for a poller-pool alert.

string

root_cause

One of:

null

null

string

Root-cause node, if this alert was attributed upstream by dependency analysis.

string format: uuid

severity

required

Severity (derived from the committed state).

string

Allowed values: info warning critical

state

required

The committed state that triggered the alert.

string

Allowed values: ok warning critical unknown unreachable maintenance

acked

One of:

null

null

object

The acknowledgement view attached to an alert / history row in API responses. Carries who acked it, when, from which external tool, and an optional note. Never carries a secret.

object

at_unix_ms

required

When the external tool recorded the ack (Unix ms, UTC).

integer format: int64

by

required

External actor reference (id / handle) — not a secret.

string

note

Optional free-text note from the external tool.

string | null

source

required

Originating tool: pagerduty | jsm | manual | …

string

subject_kind

required

What this alert is about: a monitored node, or Yagra’s own polling coverage for a pool.

string

Allowed values: node pool

subject_name

The subject’s name, for a subject identified by name rather than by id (a poller pool).

string | null

Example

[
  {
    "breach": {
      "direction": "above"
    },
    "severity": "info",
    "state": "ok",
    "subject_kind": "node"
  }
]

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