Generate (or serve from cache) an explanation of one incident.

POST

/api/v1/rca

curl --request POST \
  --url https://example.com/api/v1/rca \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "check": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "force": true, "language": "example", "node": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "window_secs": 1 }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

The POST /api/v1/rca body.

object

check

required

string format: uuid

force

Regenerate instead of serving a cached report. Still rate-limited.

boolean

language

UI language tag (ja, en-GB, …). The instructions stay English; the answer follows the reader. Unknown tags fall back to English rather than failing.

string | null

node

required

The alerting node. May be a symptom of an upstream failure — the context builder follows root_cause to the incident before assembling anything.

string format: uuid

window_secs

Timeline window in seconds; clamped by the orchestrator. Defaults to an hour.

integer | null format: int64

Example^generated

{
  "check": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "force": true,
  "language": "example",
  "node": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "window_secs": 1
}

Responses

200

The explanation and the evidence it was grounded in

Media typeapplication/json

A stored report. body carries the answer and its evidence; summary is lifted out of it so a list view does not have to fetch the whole thing.

object

body

required

The answer and the evidence it was grounded in.

object

answer

required

The parsed explanation. Every field is plain text and must be rendered as text, never as HTML or markdown — this is model output, and the model was itself reading untrusted device output.

object

confidence

How sure the model says it is.

string

Allowed values: high medium low unknown

dependents

Whether the other affected nodes are consequences of it.

string

next_steps

Concrete things to check next.

Array<string>

raw

Set when the reply was not parseable JSON: the model’s text, verbatim and bounded. Its presence is what tells the UI to render one prose block rather than empty sections.

string | null

root_cause

What most likely failed, and why the evidence says so.

string

summary

required

One sentence an on-call engineer can act on.

string

evidence

required

Everything the model was told, exactly as it saw it.

object

alert

required

The alert on that node.

object

asked_about

Set when the operator clicked a symptom and the context hopped to its cause. Naming the node they clicked keeps the answer connected to what they were looking at.

string | null

at_unix_ms

required

integer format: int64

breach

One of:

null

null

object

Numeric detail for a threshold alert; absent for liveness.

object

direction

required

Which way a metric breaches its bound.

string

Allowed values: above below

threshold

number | null format: double

value

required

number format: double

flapping

required

Whether the engine is damping this check as flapping. Worth telling the model: a flapping link and a hard failure have different causes and different next steps.

boolean

metric

required

What the check measured — icmp_rtt_ms, or the liveness sentinel.

string

severity

required

string

state

required

string

dependents

required

Alerts rolled up under this one.

object

named

required

The named dependents, capped — see total for how many there actually are.

Array<string>

total

required

How many there are in total — kept separately so truncation is visible rather than silent.

integer

generated_at_s

required

When the context was assembled (Unix seconds), so the prompt can express ages rather than absolute times the model has no clock for.

integer format: int64

node

required

The node being explained — the root cause, after any roll-up hop.

object

address

required

string

model

string | null

name

required

string

pool

Poller pool — usually the site, which is often the diagnosis (“everything in branch-osaka”).

string | null

tags

required

Operator-set grouping attributes, capped and sorted for a deterministic prompt.

Array<array>

vendor

string | null

recent_changes

required

Recent audited configuration changes touching this node.

Array<object>

One audited configuration change.

object

action

required

"{METHOD} {path}", as recorded by the audit middleware.

string

at

required

string

status

required

integer format: int32

username

required

string

root_node_id

required

Id of the node being explained. Differs from the one the operator clicked whenever the roll-up hop fired, and it is what a generated report is filed under — a report explains the cause, so it belongs to the cause.

string format: uuid

timeline

required

Cross-signal timeline for the window, oldest first.

Array<object>

One dated signal on an incident timeline (incident_correlate).

Serialize because an RCA report stores the timeline it was grounded in alongside the answer: the UI shows the two together so a reader can check the explanation against its evidence rather than taking it on faith (ADR-029).

object

at_s

required

integer format: int64

kind

required

string

label

required

string

severity

required

number format: double

upstream

required

Inventory ancestors, nearest first. Present even when healthy: “the parent is fine” is evidence that the failure is local to this node.

Array<object>

The subset of a node the model may see. Notably not the credential binding.

object

address

required

string

model

string | null

name

required

string

pool

Poller pool — usually the site, which is often the diagnosis (“everything in branch-osaka”).

string | null

tags

required

Operator-set grouping attributes, capped and sorted for a deterministic prompt.

Array<array>

vendor

string | null

window_secs

required

How far back the timeline reaches.

integer format: int64

language

required

Which language the answer was requested in.

string

Allowed values: en ja

transcript

What the model looked up for itself, in order (ADR-028 WS-G). Empty on a single-shot run, and on every report written before agentic retrieval existed.

Array<object>

One tool the model asked for, and what it was told.

Stored for the same reason evidence is: an explanation whose reader cannot check what it was based on is an assertion. Agentic retrieval makes that worse, not better — the evidence is no longer a fixed set somebody chose, so without this nobody can tell whether the model looked at the right thing.

object

args

required

The arguments the model chose.

object

result

required

What the tool answered, as the model saw it.

string

tool

required

The tool name, from the agent’s allow-list.

string

cached

Whether this response came from the cache rather than a fresh call. Not a column — it describes this delivery of the report, not the report.

boolean

check_id

required

string format: uuid

created_by

required

string

generated_at

required

string

id

required

string format: uuid

model

required

string

node_id

required

string format: uuid

provider

required

string

summary

required

string

Example

{
  "body": {
    "answer": {
      "confidence": "high"
    },
    "evidence": {
      "alert": {
        "breach": {
          "direction": "above"
        }
      }
    },
    "language": "en"
  }
}

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

404

No incident matches that node and check

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

429

Rate or concurrency cap reached; carries Retry-After

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

502

The provider failed or the model refused

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, or no LLM provider configured / configured wrongly

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