False Positive Disputes
When CleverGuard blocks content you believe is legitimate, you can dispute the finding. An LLM reviews the flagged content with context, and confirmed false positives generate tuning suggestions that an admin can apply or reject to improve future scanning accuracy.
How disputes work
When CleverGuard flags or blocks content, a scan event is logged. If you believe the finding is a false positive, you can submit a dispute against that event. Disputes and miss reports share one backend: a dispute is a feedback report with direction false_positive, while a miss report (POST /v1/guard/miss-reports) is direction false_negative— the scanner passed something it should have caught. A dispute goes through three stages:
- Submission — the report is stored with status
submitted. The disputed content is only sent to Clevername's review model if you setshare_content: true; otherwise the LLM review is skipped. - Automated LLM review — runs in the background and records a verdict, confidence, and reasoning; the report moves to
reviewed(ordismissed). - Tuning suggestion — if the false positive is confirmed, a tuning suggestion is generated, linked to the questionnaire section that drove the rule, for an admin to apply or reject.
Verdicts
| Verdict | Meaning |
|---|---|
| false_positive | The content was incorrectly flagged. The finding is dismissed and a tuning suggestion is generated. |
| true_positive | The content was correctly flagged. The original block stands. |
| inconclusive | The LLM could not determine with confidence. No tuning suggestion is generated unless the model also proposed a specific tuning change. |
Rate limits
Disputes are rate-limited to 5 per hour per user. This prevents abuse while ensuring legitimate disputes are processed promptly. The rate limit resets on a rolling window.
Find the blocked event
When content is blocked, the block response carries the scan event ID. You can also find blocked events in the SOC Console under the agent's session details. The event_id is required for a dispute.
Submit the dispute
Send a POST request to the disputes endpoint with the scan event ID and an optional reason explaining why you believe the finding is incorrect:
POST /v1/guard/disputes
Authorization: Bearer cn-live-...
{
"event_id": "a1b2c3d4-...",
"user_reason": "This SSN pattern is a product serial number, not PII",
"conversation_id": "conv_x1y2z3-...",
"message_content": "SKU-123-45-6789 is back in stock",
"share_content": true
}message_content (the blocked text, if you have it), flag_types, agent_id, reporter_confidence, and severity_estimate. Without share_content: true the dispute is stored but the LLM review is skipped, so no verdict or tuning suggestion is produced. Disputing a blocked message never releases it; if the finding is confirmed as a false positive, apply the tuning suggestion so the same content passes next time.Receive the LLM verdict
The response acknowledges the report. The LLM review runs in the background, so llm_verdict, llm_confidence, llm_reasoning, and tuning_suggestion_id are usually null at submission time and filled in when you fetch the report later:
{
"miss_report_id": "f1g2h3i4-...",
"status": "submitted",
"report_direction": "false_positive",
"llm_verdict": null,
"llm_confidence": null,
"llm_reasoning": null,
"tuning_suggestion_id": null,
"questionnaire_section": "Data (D-group, Q: D1–D3)"
}Check dispute status
Disputes and miss reports are listed together. Filter on report_direction to see only disputes; the list and detail routes return your own reports:
GET /v1/guard/miss-reports?status=reviewed&limit=50
Authorization: Bearer cn-live-...
# Or get a specific report (dispute or miss report):
GET /v1/guard/miss-reports/{miss_report_id}
Authorization: Bearer cn-live-...
# Questionnaire suggestions derived from one report:
GET /v1/guard/miss-reports/{miss_report_id}/questionnaire-suggestionsAdmin review
There is no endpoint for overriding the LLM verdict. Human judgement is applied at the tuning step: an admin decides whether to apply or reject each tuning suggestion. Every report also emails the platform admin. If the LLM verdict is inconclusive or true_positive and you still believe the block was wrong, review the agent's guardrail profile or questionnaire answers with your admin rather than re-filing the same event.
You do not have to use the API: the Report miss / Dispute FP dialog on scan-log rows, trace views, and agent scan alerts in the dashboard submits the same report.
Tuning Suggestions
When a dispute is upheld (verdict: false_positive), Clevername generates a tuning suggestion. These suggestions propose adjustments to the agent's guardrail profile to reduce future false positives for similar content.
Managing tuning suggestions
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/guard/tuning | List all pending tuning suggestions |
| POST | /v1/guard/tuning/{id}/request-approval | Send a SignedApproval request for a pending suggestion (Team/Enterprise) |
| GET | /v1/guard/tuning/{id}/approval-status | Poll the approval state for that request |
| POST | /v1/guard/tuning/{id}/apply | Apply the suggestion to the guardrail profile. Free/Pro apply directly; Team/Enterprise must go through request-approval first (a direct apply is rejected with 403) |
| POST | /v1/guard/tuning/{id}/reject | Reject the suggestion with optional notes (org admin) |
Dispute Lifecycle
Content blocked (DLP event logged)
|
v
User submits dispute
|
v
LLM automated review (only if share_content: true)
(verdict: false_positive / true_positive / inconclusive)
|
+-- true_positive --> Report reviewed, block stands
|
+-- inconclusive --> Report reviewed; suggestion only if the
| model proposed a specific tuning change
|
+-- false_positive --> Tuning suggestion generated
|
v
Admin: request-approval (Team/Enterprise) then apply, or reject
|
v
Guardrail profile updated (if applied)