Read a system's health

GET

/systems/{name}/health

const url = 'https://example.com/api/v1/systems/example/health';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/systems/example/health

The system’s current verdict and why: every role it needs filled, whether it is impaired, what an impaired role means for the system (impact), and for an impaired role which assigned components are down plus the alarms that took them down. A role that belongs to a choice (#626, an exclusive-or group such as an all-in-one alternate versus a component-built one) carries choice and alternate, and active is false when a different alternate answered the choice, meaning this role’s own impaired figure did not move the verdict. Transitions are the recorded edges over the last 30 days, one entry per change. Gated by system:read; an out-of-scope system is a non-disclosing 404.

Parameters

Path Parameters

name

required

The system’s name, or a dotted address (e.g. boi.17c.$sys.av)

string

The system’s name, or a dotted address (e.g. boi.17c.$sys.av)

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

owner

required

string

owner_kind

required

string

roles

required

The contributing roles; empty for a location

Array<object> | null

object

active

required

True for an unconditional role, or a role whose alternate is the one currently answering its choice. False means this role’s own impaired/short/spare figures did not contribute to the system’s verdict

boolean

alarms

required

The active alarms on those down components

Array<object> | null

object

component

required

string

required

string

message

required

string

raised_at

required

string format: date-time

severity

required

string

alternate

The alternate within choice this role belongs to; absent when the role is unconditional

string

assigned_to

required

Array<string> | null

choice

The choice this role belongs to; absent when the role is unconditional

string

down

required

The assigned components whose own verdict is outage; empty when the role is merely short-staffed or only degraded

Array<string> | null

impact

required

What an impaired role means for its system: outage, degraded, or none

string

impaired

required

True when satisfying is below quorum

boolean

label

required

string

name

required

string

quorum

required

integer format: int64

satisfying

required

How many assigned components currently occupy the role (their own verdict is not outage; a degraded component still occupies)

integer format: int64

short

required

How many more occupants the role needs to reach quorum, counting only those currently occupying (own verdict not outage); zero once it does. Diverges from the roles read’s understaffed when an assigned component is down

integer format: int64

spare

required

How many occupants the role has beyond quorum; zero at or below quorum

integer format: int64

systems

required

The systems beneath a location with their verdicts; empty for a system

Array<object> | null

object

name

required

string

verdict

required

string

transitions

required

The recorded edges over the window, oldest first: one entry per change, never a sample

Array<object> | null

object

required

string format: date-time

verdict

required

string

verdict

required

Healthy, incomplete, degraded, or outage: the rollup of the roles or systems served beside it. incomplete is a commissioning gap, a role short because the hardware was never installed rather than because installed hardware is failing, and it ranks between healthy and degraded

string

Example

{
  "$schema": "/api/v1/schemas/FleetHealthOutputBody.json"
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

Example

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}