Integrate diagnostic reasoning into your stack.

Overview

The AssetBlue API turns messy field evidence into an inspectable diagnosis. You send the asset and whatever you have — natural-language evidence (symptoms, diagnostics, maintenance actions), structured sensor readings, photos, HMI screenshots, voice notes — and AssetBlue reasons through failure physics and your engineering knowledge graph to a ranked root cause and the next best test.

The API is organized around a single core resource, the diagnosis. It is REST over HTTPS, returns JSON, and uses standard verbs and status codes. Every response is evidence-linked and traceable, so a recommendation never arrives without its reasoning.

• Base URL  https://api.assetblue.ai/v1
• Content type  application/json for all request and response bodies
• Evidence kinds  each evidence[] item is symptom, diagnostic, or action — all plain language
• Structured readings  send sensor / SCADA / instrument data as readings[] for charts, thresholds, and trend reasoning
• Multimodal input  attach images, audio, and HMI captures by reference on any evidence or reading

Authentication

Authenticate every request with a secret API key in the Authorization header as a bearer token. Keys are scoped per environment.

Authorization: Bearer ab_live_8f2c9d4a1b6e…

Use ab_test_… keys against the sandbox and ab_live_… keys in production. Never expose a secret key in client-side code or a mobile bundle — proxy requests through your own backend. Rotate keys from the console at any time.

Quickstart

Create your first diagnosis in one call. AssetBlue accepts whatever evidence you have and begins reasoning immediately, returning a diagnosis you can poll or subscribe to.

from assetblue import AssetBlue

ab = AssetBlue(api_key="ab_live_8f2c…")

dx = ab.diagnoses.create(
    asset={"id": "PUMP-P-104", "type": "centrifugal_pump"},
    evidence=[
        {"kind": "symptom", "text": "Rising bearing temperature with audible rumble at speed"},
        {"kind": "action",  "text": "Reapplied grease at last weekly PM, no change after 24 h"},
    ],
    readings=[
        {"metric": "bearing_temp",  "value": 82.4, "unit": "C"},
        {"metric": "vibration_rms", "value": 4.7,  "unit": "mm/s"},
    ],
)

dx = ab.diagnoses.wait(dx.id)          # block until reasoned
print(dx.leading_hypothesis.mechanism, dx.next_best_test.action)

The diagnosis lifecycle

A diagnosis moves through four states. You can act on it at any point, and a human always signs off before it becomes a finalized RCA.

Statuses surface as status on the diagnosis object: submitted, reasoning, reasoned, validated, finalized. Subscribe to webhooks to react without polling.

Endpoints

Six endpoints cover the full lifecycle: create, retrieve, enrich, validate, report, and recall. Paths are relative to the base URL.

{
  "asset": { "id": "PUMP-P-104", "type": "centrifugal_pump" },
  "evidence": [
    {
      "kind": "symptom",
      "text": "Bearing temp creeping up over the last shift, audible rumble at speed",
      "at": "2026-06-04T13:47Z"
    },
    {
      "kind": "diagnostic",
      "text": "Spectrum shows clear 1x and 2x bearing sidebands; pattern matches an outer-race defect",
      "at": "2026-06-04T13:55Z",
      "attachments": ["upl_2Hk…"]
    },
    {
      "kind": "action",
      "text": "Reapplied grease at last weekly PM — no change in vibration after 24 h",
      "at": "2026-06-03T09:00Z"
    }
  ],
  "readings": [
    { "metric": "bearing_temp",  "value": 82.4, "unit": "C",    "at": "2026-06-04T13:55Z" },
    { "metric": "vibration_rms", "value": 4.7,  "unit": "mm/s", "at": "2026-06-04T13:55Z" }
  ]
}

{
  "id": "dg_3Qa9kR2xVb",
  "status": "reasoning",
  "asset": { "id": "PUMP-P-104", "type": "centrifugal_pump" },
  "created_at": "2026-06-04T14:18:07Z"
}

{
  "id": "dg_3Qa9kR2xVb",
  "status": "reasoned",
  "leading_hypothesis": {
    "mechanism": "bearing_fatigue.outer_race_spalling",
    "confidence": 0.86,
    "evidence_for": [
      { "claim": "BPFO spectral peak matches pump RPM", "source": "vibration" },
      { "claim": "Localized housing hotspot, not winding", "source": "thermal" }
    ],
    "evidence_against": [
      { "claim": "No lubricant odour reported", "source": "voice_note" }
    ]
  },
  "next_best_test": {
    "action": "Run envelope/SEE bearing spectrum at 2x RPM",
    "expected_confidence": 0.97
  }
}

{
  "kind": "diagnostic",
  "text": "Envelope spectrum at 2x RPM shows a clean BPFO peak; outer race confirmed",
  "at": "2026-06-04T15:02Z",
  "attachments": ["upl_9Wq…"]
}

{
  "engineer": { "id": "u_8821", "name": "R. Okafor" },
  "decision": "confirm",
  "note": "Spectrum confirms outer-race spalling. Schedule replacement."
}

Webhooks

Subscribe to events instead of polling. AssetBlue POSTs a signed JSON payload to your endpoint when a diagnosis changes state.

• diagnosis.reasoned — hypotheses and next best test are ready
• diagnosis.validated — an engineer has signed off
• diagnosis.finalized — the RCA report is available

Verify authenticity with the AssetBlue-Signature header (HMAC-SHA256 over the raw body using your signing secret). Respond 2xx within 5 seconds; failed deliveries retry with backoff for 24 hours.

SDKs

Official libraries wrap auth, retries, pagination, and webhook verification.

pip install assetblue

npm install @assetblue/sdk

Prefer raw HTTP? Every example here is a plain request you can run with curl or any client. The OpenAPI spec is published at /v1/openapi.json.

Errors & limits

AssetBlue uses conventional HTTP status codes and returns a structured error body.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "asset.id is required",
    "param": "asset.id"
  }
}

Send an Idempotency-Key header on writes to safely retry without creating duplicate diagnoses.