Doctor API Reference

Operations

GET /api/v1/buildinfo

API alias for /buildinfo.json (same payload).

Responses:

GET /api/v1/doctor/checks

List available doctor checks

Returns all health checks available in the Doctor engine, optionally filtered by category or plugin. Each check includes its ID, name, category, and description. Requires doctor:run authorization.

Parameters:

Responses:

POST /api/v1/doctor/diagnosis

Generate AdvisoryAI diagnosis for a Doctor run

Generates an AI-powered diagnosis and remediation recommendations for a completed Doctor run. Returns structured findings with severity, root cause analysis, and suggested actions. Requires doctor:run authorization.

Responses:

GET /api/v1/doctor/plugins

List available doctor plugins

Returns all registered Doctor plugins with their names, versions, and available check categories. Requires doctor:run authorization.

Responses:

POST /api/v1/doctor/remediate

Trigger a gated Doctor self-healing remediation

Resolves a failing check’s declared heal and runs it through the gated executor (ADR-026 D5): a non-destructive action auto-runs only within a maintenance window under the rate-limit; a destructive action runs only behind the full gate (approval token + dry-run preview + active window + durable audit + rate-limit), else it falls back to manual guidance. Returns the per-action outcome (executed | dry-run-preview | deferred | manual-guidance). Every call writes a durable audit row. Requires doctor:remediate authorization.

Responses:

GET /api/v1/doctor/remediations

List recent remediation-audit rows

Returns the most recent gated remediation decisions (newest first) from the durable audit, for attribution. The approval token value is never stored (presence only). Requires doctor:remediate or doctor:admin authorization.

Parameters:

Responses:

GET /api/v1/doctor/reports

List historical doctor reports

Returns paginated historical Doctor run reports with summary metadata including run date, mode, overall health status, and check counts. Requires doctor:run authorization.

Parameters:

Responses:

GET /api/v1/doctor/reports/{reportId}

Get a specific doctor report

Returns the full stored Doctor report for a specific report ID including all check results and diagnosis if available. Returns 404 if the report is not found. Requires doctor:run authorization.

Parameters:

Responses:

DELETE /api/v1/doctor/reports/{reportId}

Delete a doctor report

Permanently removes a stored Doctor report. Returns 204 No Content on success or 404 if not found. Requires doctor:admin authorization.

Parameters:

Responses:

POST /api/v1/doctor/run

Start a new doctor run

Initiates a new Doctor health check run with the specified mode, categories, and plugins. Returns 200 OK with the run ID and initial “running” status. Results are retrieved via GetDoctorRunResult or streamed via StreamDoctorRunProgress. Requires doctor:run authorization.

Responses:

GET /api/v1/doctor/run/{runId}

Get doctor run result

Returns the full result of a completed Doctor run including per-check outcomes, overall health status, and failure summary. Returns 404 if the run is not found. Requires doctor:run authorization.

Parameters:

Responses:

GET /api/v1/doctor/run/{runId}/stream

Stream doctor run progress via SSE

Streams real-time progress events for an active Doctor run using Server-Sent Events (text/event-stream). Each event contains the check ID, status, and message. Requires doctor:run authorization.

Parameters:

Responses:

GET /buildinfo.json

Image build provenance (module, gitSha, gitCommitTime, imageBuiltAt, branch) for drift detection.

Responses:

GET /healthz

Responses:

POST /internal/plugins/probe

Responses:

GET /internal/plugins/status

Responses:

GET /readyz

Responses: