# Diagnostics API

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

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.

## Related Pages

- [Findings](./findings.md)
- [Trace diagnosis with CLI](./trace-diagnosis.md)
- [API reference](./api-reference.md)