---
title: "Root Cause"
method: POST
path: "/api/agents/root-cause"
---

# Root Cause

`POST /api/agents/root-cause`

## Request

- Base URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com`
- URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com/api/agents/root-cause`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Analyzes supplied incident-window and historical context; it does not directly access customer systems. Included in dxpert Pro; a free account may use its Try Pro runs (5 lifetime, pooled across agents), after which the endpoint answers 402 pro_required. API key or bearer authentication is required; a successful run uses the dxpert Pro allowance or one Try Pro run. No billing, email, or persistent server state is changed.

## Headers

- `Authorization` string, nullable
- `X-Api-Key` string, nullable

## Request body

- RootCauseRequest
  - `alarms` AlarmRecord[]
    - `code` string, required
    - `priority` integer, nullable
    - `source` string, required
    - `text` string, required
    - `ts` string, date-time, required
  - `config` object, nullable
  - `downtime` ShiftDowntimeRecord[]
    - `category` string, required
    - `cell` string, required
    - `end` string, date-time, required
    - `reason` string, required
    - `start` string, date-time, required
  - `events` ShiftRawEvent[]
    - `payload` union, required
      - string
      - integer
      - number
      - boolean
      - object
    - `topic` string, required
    - `ts` string, date-time, required
  - `genealogy` RootCauseGenealogyRecord[]
    - `cell` string, required
    - `lot` string, required
    - `material` string, required
    - `supplier` string, nullable
    - `ts` string, date-time, required
  - `notes` string[]
  - `production` ShiftProductionRecord[]
    - `cell` string, required
    - `good_count` integer, required
    - `scrap_count` integer, required
    - `ts` string, date-time, required
  - `quality` ShiftQualityRecord[]
    - `cell` string, required
    - `disposition` string, required
    - `issue` string, required
    - `ts` string, date-time, required
  - `question` string, required
  - `series` RootCauseSeries[]
    - `name` string, required
    - `points` RootCauseSeriesPoint[], required
      - `ts` string, date-time, required
      - `value` number, required
    - `unit` string, nullable
  - `site_profile` RootCauseSiteProfile, required
    - `baseline_end` string, date-time, nullable
    - `baseline_start` string, date-time, nullable
    - `language` 'en' | 'fr' | 'de' | 'es'
    - `line` string, required
    - `plant` string, required
    - `shift_label` string, required
    - `window_end` string, date-time, required
    - `window_start` string, date-time, required

## Response `200`

Successful Response

- RootCauseResponse
  - `candidates` RootCauseCandidate[], required
    - `cause` string, required
    - `confidence` 'high' | 'medium' | 'low', required
    - `evidence_ids` string[], required
    - `rationale` string, required
    - `score` number, required
    - `source` string, required
  - `coverage` RootCauseCoverage, required
    - `change_points` object[]
    - `gaps` string[]
    - `mode` 'structured', required
    - `records_baseline` object, required
    - `records_in_window` object, required
  - `evidence` RootCauseEvidenceRow[], required
    - `detail` string, required
    - `id` string, required
    - `label` string, required
    - `source` string, required
    - `ts` string, date-time, required
    - `value` number, nullable
  - `namespace_recommendations` ShiftNamespaceRecommendation[]
    - `gap` string, required
    - `recommended_topics` string[], required
    - `unlocks` string, required
  - `report_markdown` string, required

## Other responses

- `401`: Missing, malformed, or invalid credentials.
- `402`: Credentials are valid but the account's plan does not include this capability (for example, Try Pro is used up and dxpert Pro is not active).
- `422`: Validation Error
- `429`: The applicable rate or quota limit has been reached. `quota_exceeded` names the limit in `scope` (for example `free_quota`: the free Advisor's 10 questions this month). `pro_allowance_exhausted`: the dxpert Pro monthly allowance, shared by the Advisor and every agent, is used up; service resumes when it renews (`resets_at`). There is no overage and nothing extra to buy.
- `502`: `llm_error`: the language-model provider failed. Retry later.

---

[API](https://skmtc.dev/dxpert/apis/dxpert-ai-api.md) · [All operations](https://skmtc.dev/dxpert/apis/dxpert-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dxpert/apis/dxpert-ai-api/revisions/460f1c8c53d1?raw)