Skip to content
Yagra

Reachability of the backing services plus the indirect bus signal.

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

Takes State rather than the Admin extractor on purpose: in skeleton mode this answers a "degraded" body naming what is missing, not a 503. This is the page you open when something is already broken.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Per-dependency reachability; skeleton mode answers a degraded body rather than 503

Media typeapplication/json

Yagra’s own health: the reachability of its backing services.

object
bus
required

NATS — inferred from a recent scheduler sweep, not a direct ping.

object
detail
required
string
reachable
required
boolean
flow
required

ClickHouse (flow store, ADR-031) — likewise reachable when not configured.

object
detail
required
string
reachable
required
boolean
logs
required

VictoriaLogs (event log, ADR-024) — reported reachable when not configured (events then live in PostgreSQL), so an unconfigured log store never degrades overall.

object
detail
required
string
reachable
required
boolean
overall
required

"ok" when every dependency is reachable, else "degraded".

string
postgres
required

PostgreSQL (metadata store) — SELECT 1.

object
detail
required
string
reachable
required
boolean
tsdb
required

VictoriaMetrics (TSDB) — /-/healthy.

object
detail
required
string
reachable
required
boolean
web_tls
required

The WebUI’s TLS certificate. Reported unhealthy only when someone has to act: it has expired, or an imported certificate is inside its last 30 days. A self-signed one renews itself.

object
detail
required
string
reachable
required
boolean
Examplegenerated
{
  "bus": {
    "detail": "example",
    "reachable": true
  },
  "flow": {
    "detail": "example",
    "reachable": true
  },
  "logs": {
    "detail": "example",
    "reachable": true
  },
  "overall": "example",
  "postgres": {
    "detail": "example",
    "reachable": true
  },
  "tsdb": {
    "detail": "example",
    "reachable": true
  },
  "web_tls": {
    "detail": "example",
    "reachable": true
  }
}

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