Skip to content

Diagnostics API

The Diagnostics API exposes Findings, diagnostic settings, built-in Rules, Rule Runs, backfills, and repair handoff.

View as Markdown Open the plain-text version of this page.

Base URL:

text
https://api.provon.dev/v1

Project API keys need diagnostics:read for read routes and diagnostics:write for mutation routes. Signed-in Workbench sessions can use the same project-qualified routes when the user has the corresponding project permission.

Findings#

Method Path Purpose
GET /projects/:projectId/diagnostics/findings List Findings
GET /projects/:projectId/diagnostics/findings/:findingId Read one Finding
PATCH /projects/:projectId/diagnostics/findings/:findingId Update review or repair fields
POST /projects/:projectId/diagnostics/findings/:findingId/repair-handoff Create a repair issue and mark the Finding confirmed

List query parameters:

Parameter Type Notes
reviewStatus unreviewed, confirmed, or dismissed Optional filter
minDiagnosticScore number from 0 to 1 Optional filter
limit integer from 1 to 500 Optional result limit

Supported PATCH fields:

json
{
  "reviewStatus": "confirmed",
  "repairHandoffRef": "github:owner/repo#42",
  "resolvedAt": 1760000000000
}

reviewStatus can be unreviewed, confirmed, or dismissed. repairHandoffRef and resolvedAt can also be null.

Repair handoff requires a configured repair gateway. The current repair gateway opens a GitHub Issue and stores a reference in the form github:owner/repo#number.

Settings#

Method Path Purpose
GET /projects/:projectId/diagnostics/settings Read automatic scheduling settings
PATCH /projects/:projectId/diagnostics/settings Enable or disable automatic scheduling

Patch body:

json
{
  "automaticSchedulingEnabled": true
}

Rules#

Method Path Purpose
GET /projects/:projectId/diagnostics/rules List built-in Rules and configuration
PATCH /projects/:projectId/diagnostics/rules/:ruleId Enable/disable or reconfigure one Rule
POST /projects/:projectId/diagnostics/rules/:ruleId/backfills Queue a time-window backfill

Patch either enabled:

json
{
  "enabled": false
}

or configuration:

json
{
  "configuration": {
    "keywords": ["checkout", "payment"],
    "minSignalScore": 0.25,
    "minDiagnosticConfidence": 0.5,
    "adjudicationMode": "auto",
    "adjudicationModel": null,
    "signalOverrides": {
      "runtime_error": { "enabled": true, "severity": "high" }
    }
  }
}

adjudicationMode can be auto or deterministic-only. Signal override severities can be critical, high, medium, low, or info.

Backfill body:

json
{
  "startMs": 1760000000000,
  "endMs": 1760086400000,
  "limit": 100
}

Backfill responses use 202 when Runs are queued.

On-Demand Runs#

Queue enabled Rules for one conversation activity snapshot:

http
POST /v1/projects/:projectId/diagnostics/rule-runs
json
{
  "conversationId": "conv_123",
  "lastActivityAt": 1760000000000,
  "traceIds": ["trace_123"]
}

conversationId and lastActivityAt are required. traceIds is optional and is filtered to string values.