Skip to main content
All updates
Product

Suggestions now carry the model's reasoning

Why a span was suggested, how confident the agent is, and what to do about it. All on the suggestion response now.

Edward Coleridge Smith

3 min read

Until today, a POST /v1/suggestions response told you where the agent thought a redaction belonged, and not much else. From today, every suggestion in the response also carries four new properties by default — source, reason, confidence, and recommendation — with two more, text and explanation, available on request via sparse fieldsets.

This is the part of the API most reviewer UIs were having to fake: bolting on confidence heuristics, guessing at categories, or rendering "the agent says so" boxes and hoping the human reviewer would just trust the call. Now the model's reasoning rides along with the span itself.

What's in each suggestion ​

Each entry in data.attributes.annotations[] — fully expanded, with text and explanation requested via ?fields[annotations]=text,explanation — now looks like this:

json
{
  "page": 2,
  "rect": { "x": 120, "y": 340, "width": 78, "height": 18 },
  "source": "agent",
  "text": "Jane Doe",
  "reason": "personal_name",
  "confidence": 0.94,
  "explanation": "Appears in the salutation of a personal letter, paired with a residential address two lines below.",
  "recommendation": "redact"
}

A quick tour of the new fields:

  • source — where the suggestion came from. "agent" for spans the agent itself flagged, or "risky_annotation" for sensitive content found inside existing PDF annotations (highlights, comments, squares). Useful when you want to render, route, or audit them differently.
  • text (opt-in) — the literal text the agent matched. Lets you key UI state (a "redact this everywhere" toggle, for example) on the string itself rather than the span.
  • reason — a short machine-readable category. Stable across versions; safe to switch on.
  • confidence — a score in [0, 1]. Calibrated per agent; not directly comparable across agents.
  • explanation (opt-in) — a one- or two-sentence natural-language rationale. Written to be shown to a human reviewer as-is.
  • recommendation — the agent's own call on what should happen, separate from whether it spotted something.

text and explanation are returned only when explicitly requested via sparse fieldsets; the other four are on every suggestion by default. The full schema, including the sparse-fieldset query syntax, lives at docs.redactr.io.

What this unlocks ​

Two patterns we already see customers reaching for:

Filter or route by confidence. Auto-apply suggestions where confidence is high and recommendation is redact; queue the rest for a human. The agent already makes the obvious calls; this lets you stop paying a reviewer for them.

Show the explanation in your reviewer UI. A reviewer who can see why the agent flagged a span resolves it in a fraction of the time, and disagreements become useful feedback rather than noise.

Backwards compatibility ​

Existing consumers don't need to change anything. The new properties are additive; old fields are unchanged. If your client deserialises into a strict struct that rejects unknown fields, loosen it before pulling this update.