# 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.

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`.

## Related Pages

- [Findings](../findings/index.md)
- [Trace diagnosis with CLI](../cli/diagnose.md)
- [API reference](./index.md)