# Findings API

Paths on this page are relative to `https://shruwd.io/api/v1`.

| Method | Path | Scope | Role |
|---|---|---|---|
| `GET` | `/brands/{brandId}/findings` | `read` | viewer |
| `GET` | `/findings/{findingId}` | `read` | viewer |
| `POST` | `/findings/{findingId}/transition` | `write` | editor |

`{findingId}` accepts the finding's id or its `number` — 1, 2, 3… per workspace in
first-seen order, never reused.

## List findings

```bash
curl "https://shruwd.io/api/v1/brands/waitlister/findings?states=open,acknowledged" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"
```

Ordered the way the dashboard and the digest order them: severity, then confidence, then
estimated impact.

Every row carries `confidence`, which decides how much weight a finding deserves:

| Confidence | Meaning |
|---|---|
| `observed` | A first-party fact, from your own logs or a live fetch of your page |
| `inferred` | Not directly observed, but every link in the chain is checkable in the evidence |
| `heuristic` | A correlation from comparing your pages with the ones being cited. A lead, not a fact |

Never present a `heuristic` finding as a fact.

If your plan caps visible findings, the rest are counted in `locked` rather than hidden,
and fetching one is `403 not_entitled`.

Findings reads are **not** clamped to your history window — a finding older than the
window is still a finding.

## Get one finding

Returns the full evidence, the recommendation's steps, and:

| Field | |
|---|---|
| `baseline` | The snapshot captured at `fix_applied`: metric values, intervals, `n`, timestamp |
| `stateChangedAt` | When it entered its current state |
| `events` | Newest first, each with the payload it recorded — a recheck verdict's per-prompt gates are readable here |
| `suppressedBy` · `suppressedByNumber` | Set when a more fundamental finding on the same URL is masking this one |

Suppression matters: there is no point restructuring a page for citation while your server
is refusing the crawler that would read it.

## Transition a finding

```bash
curl -X POST "https://shruwd.io/api/v1/findings/7/transition" \
  -H "Authorization: Bearer $SHRUWD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"fix_applied","note":"Removed the Disallow for OAI-SearchBot"}'
```

`to` is one of:

| Value | Meaning |
|---|---|
| `acknowledged` | You have picked it up |
| `fix_applied` | The change is live. **Captures the baseline** and returns when the recheck will run |
| `dismissed` | Not a problem. Quiet for 90 days, then it may return |

> **Warning**
>
> `resolved` and `not_moved` are **refused**. Those verdicts belong to the recheck, which
> compares the baseline against a fresh measurement — they are not something a caller, human
> or agent, can assert. See [Rechecks](https://shruwd.io/docs/findings/rechecks.md).

Mark `fix_applied` only once the change is live. The baseline is captured at that moment,
so marking it early compares your change against itself.

## Next steps

- [How findings work](https://shruwd.io/docs/findings/how-findings-work.md) — the full lifecycle
- [Rechecks](https://shruwd.io/docs/findings/rechecks.md) — how the verdict is decided