Skip to content

Findings API

The Findings API exposes Finding clusters and occurrences, diagnostic settings, built-in Rules, queryable Rule Runs and backfills, and provider-neutral repair work items.

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 Finding clusters
GET /projects/:projectId/diagnostics/findings/:findingId Read one Finding and its latest occurrence
GET /projects/:projectId/diagnostics/findings/:findingId/occurrences List occurrence history
PATCH /projects/:projectId/diagnostics/findings/:findingId Update review or resolution state
POST /projects/:projectId/diagnostics/findings/:findingId/work-items Create and confirm a repair handoff

List query parameters:

Parameter Type Notes
reviewStatus unreviewed, confirmed, or dismissed Optional filter
resolutionStatus Finding resolution status Optional filter
severity Finding severity Optional filter
minDiagnosticScore number from 0 to 1 Optional filter
lastDetectedAfter Unix milliseconds Inclusive lower bound
lastDetectedBefore Unix milliseconds Exclusive upper bound
limit integer from 1 to 500 Page size
cursor opaque string Cursor from prior result

List responses include pagination.limit and pagination.nextCursor.

Supported PATCH fields:

json
{
  "reviewStatus": "confirmed"
}

reviewStatus can be unreviewed, confirmed, or dismissed. Manual resolution uses resolutionStatus: "resolved" | "unresolved". Dismissal atomically clears resolution state.

Work-item creation accepts provider: "github" | "gitlab" | "linear" | "jira" and an optional provider destination. The configured connector default is used when destination is omitted.

Lifecycle actions:

text
POST .../work-items/:workItemId/sync
POST .../work-items/:workItemId/retry
POST .../work-items/:workItemId/replacements
POST .../work-items/:workItemId/abandon

Replacement accepts the same provider and destination body as creation. Abandoning only detaches the local handoff; it does not close the external issue.

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,
  "maxConversations": 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.

Execution History#

text
GET /v1/projects/:projectId/diagnostics/rule-runs
GET /v1/projects/:projectId/diagnostics/rule-runs/:runId
GET /v1/projects/:projectId/diagnostics/backfills
GET /v1/projects/:projectId/diagnostics/backfills/:backfillId

Run lists support status, origin, ruleId, backfillId, conversationId, limit, and cursor. Backfill lists support scanStatus, ruleId, limit, and cursor.

Runs expose queued, running, completed, skipped, and failed states, including attempts, result count, skip reason, and error message. Backfill projections additionally aggregate child-run progress and report queued, scanning, processing, completed, completed_with_errors, or failed.