---
title: "Diagnostic"
method: POST
path: "/api/diagnostic"
---

# Diagnostic

`POST /api/diagnostic`

## Request

- Base URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com`
- URL: `https://opwhcervi3.execute-api.ca-central-1.amazonaws.com/api/diagnostic`
- Auth: one of:
  - none
  - API key in header `X-Api-Key`

Runs the preliminary self-reported readiness diagnostic. The scores and verdict are rule-based; the written report is generated by a language model grounded on dxpert's knowledge base, so its wording can vary between calls. Every response is `scope: preliminary`. Authentication is optional via API key; it uses no entitlement, trial run, billing, email, or persistent state, but is quota/rate limited. 502 `llm_error` when the model provider fails.

## Query parameters

- `token` string, nullable

## Headers

- `X-Api-Key` string, nullable
- `X-Access-Token` string, nullable

## Request body

- IntakeModel: The 16-question intake. Field order matches the spec table.
  - `ai_ambition` AiAmbition, required
    - `target` 'pilot' | 'scale' | 'autonomous', required
    - `text` string, required
  - `common_model` 'none' | 'per_system' | 'partial' | 'unified', required
  - `data_off_floor` 'manual' | 'scada_only' | 'opcua' | 'mqtt_sparkplug' | 'mixed', required
  - `data_ownership` 'tribal' | 'unclear' | 'owned_governed', required
  - `data_ready_for_use_case` 'no' | 'partial' | 'yes', required
  - `edge_vs_poll` 'poll' | 'mixed' | 'edge_push', required
  - `historian_depth` 'none' | 'local' | 'central_untrusted' | 'central_trusted', required
  - `otit_security` 'ad_hoc' | 'partial' | 'governed', required
  - `personal_stakes` string, required
  - `politically_useful` string, required
  - `prior_attempts` string, required
  - `realtime_visibility` 'none' | 'on_request' | 'partial' | 'single_pane', required
  - `sector` 'discrete_mfg' | 'automotive' | 'process' | 'pharma' | 'food_bev' | 'energy' | 'other', required
  - `site_count` integer, required
  - `uns_state` 'none' | 'point_to_point' | 'partial' | 'governed_uns', required
  - `who_they_trust` string, required

## Response `200`

Successful Response

- DiagnosticResult
  - `next_step` DiagnosticNextStep: The one action that follows from THIS result. Without it the free surface simply ends: a caller learns their namespace is broken and is pointed back at more free tools. An MCP client can read this aloud to its principal. It never enlarges what the diagnostic claims -- `scope` stays "preliminary" regardless of what this says.
    - `account_required` boolean
    - `free` boolean
    - `summary` string, required
    - `url` string, required
  - `report_markdown` string, required
  - `scope` string
  - `scores` ScoresModel, required
    - `acatech_stage` integer, required
    - `ai_readiness_gate` string[], required
    - `axes` object, required
    - `confidence` number, required

## Other responses

- `401`: Missing, malformed, or invalid credentials.
- `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)