Build on Shruwd

Findings API

Read the diagnoses behind your numbers and transition them as you act on each one.

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

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

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/waitlister/findings?states=open,acknowledged" `
  -Headers @{ Authorization = "Bearer $env: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

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"}'

Invoke-RestMethod -Method Post -Uri "https://shruwd.io/api/v1/findings/7/transition" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" } `
  -ContentType "application/json" `
  -Body '{"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

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.

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 — the full lifecycle
Rechecks — how the verdict is decided