Integrate diagnostic reasoning into your stack.

Start a diagnosis from any combination of evidence. Returns immediately with a diagnosis in the reasoning state.

{
  "asset": { "id": "TX-4021", "type": "transformer" },
  "evidence": [
    {
      "kind": "symptom",
      "text": "Top-oil temperature climbing over the last week at unchanged load; Buchholz alarmed once overnight",
      "at": "2026-06-04T13:47Z"
    },
    {
      "kind": "diagnostic",
      "text": "Latest DGA shows acetylene with rising ethylene — a high-energy internal fault signature",
      "at": "2026-06-04T13:55Z",
      "attachments": ["upl_2Hk…"]
    },
    {
      "kind": "action",
      "text": "Cooler-bank fans serviced last month — no change in the top-oil trend",
      "at": "2026-06-03T09:00Z"
    }
  ],
  "readings": [
    { "metric": "top_oil_temp",  "value": 82.4, "unit": "C",    "at": "2026-06-04T13:55Z" },
    { "metric": "acetylene", "value": 4.7,  "unit": "ppm", "at": "2026-06-04T13:55Z" }
  ]
}

{
  "id": "dg_3Qa9kR2xVb",
  "status": "reasoning",
  "asset": { "id": "TX-4021", "type": "transformer" },
  "created_at": "2026-06-04T14:18:07Z"
}

Retrieve the current reasoning state: ranked hypotheses, the evidence weighed for and against each, and the single next test that best discriminates the cause.

{
  "id": "dg_3Qa9kR2xVb",
  "status": "reasoned",
  "leading_hypothesis": {
    "mechanism": "internal_arcing.high_energy_discharge",
    "confidence": 0.86,
    "evidence_for": [
      { "claim": "Acetylene present with rising ethylene — high-energy fault signature", "source": "dga" },
      { "claim": "Top-oil rise decoupled from load", "source": "thermal" }
    ],
    "evidence_against": [
      { "claim": "No gas accumulation in the Buchholz relay on inspection", "source": "field_note" }
    ]
  },
  "next_best_test": {
    "action": "Repeat DGA at 48 h and run a Duval triangle on the trend",
    "expected_confidence": 0.97
  }
}

Append one or more evidence items to an in-flight diagnosis — same shape as the evidence array on POST /v1/diagnoses. AssetBlue re-reasons and returns the updated diagnosis with revised confidence. To answer a clarifying question AssetBlue raised, set in_reply_to to its question_id.

{
  "kind": "diagnostic",
  "text": "Repeat DGA at 48 h: acetylene up to 21 ppm; Duval places it in D2 (high-energy arcing)",
  "at": "2026-06-04T15:02Z",
  "attachments": ["upl_9Wq…"]
}

Record a named engineer's decision. No work order is issued without sign-off. decision is confirm or override; on confirm a final reasoning pass emits the formal RCA and the diagnosis moves to finalized (fetch it via GET /rca), on override the note is recorded and the diagnosis stays validated. Returns the updated diagnosis object. Pass ?wait=true to block until the finalize pass completes.

{
  "decision": "confirm",
  "engineer_name": "R. Okafor",
  "engineer_email": "r.okafor@example.com",
  "note": "DGA trend confirms high-energy arcing. De-energize and schedule an internal inspection."
}

Fetch the formal root-cause report: the confirmed root cause, causal chain, key evidence, eliminated causes, recommended actions with owners and due dates, confidence progression, and referenced standards. Finalizes on demand — if the diagnosis has no report yet, this runs the finalize reasoning pass inline and returns the result, so create → evidence → GET /rca works without an explicit /validate call (/validate remains the way to record engineer sign-off). Default response is JSON; pass ?format=pdf to download the same report as a formatted PDF (application/pdf).

Your onboarded assets — the same register the web app shows, scoped to the account that created the API key. Use it to discover the asset ids (plus manufacturer/model context) to feed into /v1/diagnoses and /v1/whatif without re-entering them.

{
  "assets": [
    {
      "id": "seed-tx-bhel-220",
      "name": "GT-1 — BHEL 160 MVA 220/66 kV",
      "asset_type": "transformer",
      "manufacturer": "BHEL",
      "model_number": "220/66 kV, 50, 100 & 160 MVA POWER TRANSFORMER",
      "envelope_rows": 6
    }
  ],
  "count": 1
}

Recall an asset’s accumulated memory: prior evidence (symptoms, diagnostics, and maintenance actions), confirmed mechanisms, corrective actions, and recurrence patterns. Every new diagnosis starts from this intelligence, not a blank form.

The assets we support right now: boiler and transformer. This endpoint lists them, which skills each can run, and the state of its binary. Every asset_type you send must be one of these — anything else is a 400, never a silent default. Availability is live: what-if works for both off the knowledge base; the boiler binary is an extra engine for boilers, and the transformer binary is not built yet — it’s on the way.

{
  "supported": ["boiler", "transformer"],
  "asset_types": [
    { "asset_type": "boiler", "label": "Boiler", "supported": true,
      "skills": {
        "rca": { "available": true },
        "whatif": { "available": true, "engines": { "envelope_assessment": true, "boiler_binary": true } },
        "knowledge": { "available": true } },
      "binary": { "name": "boiler_binary", "available": true, "status": "available" } },
    { "asset_type": "transformer", "label": "Transformer", "supported": true,
      "skills": {
        "rca": { "available": true },
        "whatif": { "available": true, "engines": { "envelope_assessment": true, "transformer_binary": false } },
        "knowledge": { "available": true } },
      // the transformer binary is not built yet
      "binary": { "name": "transformer_binary", "available": false, "status": "on_the_way" } }
  ]
}

Look up the manufacturers and models you can address on a skill call. This is the catalog index — names only. It is a lookup, not a directory dump: manufacturers need a q (2+ chars), models are always scoped to one manufacturer, results are capped with a truncated flag, and there is no offset/cursor to walk. The knowledge itself — envelopes, mechanisms, diagnostics, documents — is never returned here; it stays behind the skills.

{ "asset_type": "boiler", "q": "bhel" }

{
  "asset_type": "boiler", "q": "bhel",
  "manufacturers": [ { "manufacturer": "Bharat Heavy Electricals Limited", "models": 12 } ],
  "returned": 1, "truncated": false
}

{ "asset_type": "boiler", "manufacturer": "Bharat Heavy Electricals Limited" }
// → { "models": ["200/210 MW Subcritical …", …], "returned": 12, "truncated": false }

What a what-if run accepts, keyed by asset_type — every family in one response, so there is no discriminator to pass (asset_type is only ever a body field on POST). Each asset type reports whatif.available (true for both — it runs off the knowledge base), its accepted inputs, and its engines: envelope_assessment (always available, no binary) plus the binary — boiler_binary (live, with its primitives/controls/mechanisms) or transformer_binary (on_the_way).

One what-if endpoint for every asset. The engine is chosen by the asset’s family (inferred from asset, or set asset_type explicitly) — there is no per-asset-type path. A boiler runs the boiler binary; a transformer is assessed against its operating envelope. The response carries asset_type and engine so you know which result shape you got. Boiler runs are synchronous (a few seconds); transformer assessments honour ?wait (default true returns the result; false returns a job to poll at GET /whatif/{id}).

Transformer: its what-if works today (knowledge base). Only the transformer binary is on the way — so primitive is the one input it doesn’t take, and sending it returns 501 Not Implemented saying so rather than quietly running something else.

{
  "asset_type": "boiler",
  "asset": { "model": "200/210 MW subcritical" },
  "primitive": "chemistry_excursion",
  "params": { "species": "pH_low", "value": 8.2, "duration": "72h" },
  "horizon": "90d"
}

{
  "asset_type": "boiler",
  "asset": { "manufacturer": "BHEL", "model": "200/210 MW subcritical" },
  "change": "two-shift the unit daily for the next quarter"
}

// …or structured conditions, on any asset type:
{
  "asset_type": "transformer",
  "asset": { "manufacturer": "ABB", "model": "TrafoStar 400" },
  "proposed": { "load_pct": 118, "top_oil_C": 98, "duration": "6h" }
}

{
  "id": "wif_73a7fdbdad",
  "skill": "whatif",
  "status": "done",
  "result": {
    "asset_type": "boiler",
    "engine": "boiler_binary",
    "prognosis": { "governing_mechanism": { "name": "Hydrogen damage" }, "failure_risk_pct": 12.0, "remaining_life_days": 540 },
    "final_state_token": "…"
  }
}

A transformer result instead carries "engine": "envelope_assessment" with an assessment (headroom, risks, go/caution/no-go) and envelopes_considered.

Recall a stored what-if run by id (scoped to your key). GET /v1/whatif lists your recent runs. For a transformer run started with ?wait=false, poll here until status is done.

Knowledge Q&A. Answer a technical reliability question, grounded in the knowledge base and scrubbed of source names. Default ?wait=true returns the answer directly; ?wait=false returns a job to poll at GET /v1/answers/{id}.

{
  "question": "What causes waterwall tube hydrogen damage and how is it detected?",
  "asset_type": "boiler"
}

{
  "id": "ans_1b7c9d0e2f",
  "skill": "knowledge_answer",
  "status": "done",
  "result": {
    "answer": "## Causes … (markdown, no source names)",
    "grounded": true,
    "asset_type": "boiler",
    "sources_considered": 8
  }
}