False Positive Disputes
When CleverGuard blocks content you believe is legitimate, you can dispute the finding. An LLM reviews the flagged content with full context, and SOC admins can override the verdict. Upheld disputes generate tuning suggestions to improve future scanning accuracy.
How disputes work
When CleverGuard flags or blocks content, a DLP event is logged. If you believe the finding is a false positive, you can submit a dispute against that event. Clevername runs a three-stage review process:
- Automated LLM review — an LLM evaluates the flagged content with the full conversation context and returns a verdict.
- SOC admin human review — a human administrator can override the LLM verdict if needed.
- Tuning suggestion — if the dispute is upheld (false positive confirmed), a tuning suggestion is generated to adjust the guardrail profile.
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. Escalated for human review. |
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 response includes a dlp_event_id. You can also find blocked events in the SOC Consoleunder the agent's session details.
Submit the dispute
Send a POST request to the disputes endpoint with the DLP event ID and an optional reason explaining why you believe the finding is incorrect:
POST /v1/guard/disputes
Authorization: Bearer cnk_grd_...
{
"dlp_event_id": "evt_a1b2c3d4-...",
"user_reason": "This SSN pattern is a product serial number, not PII",
"conversation_id": "conv_x1y2z3-...",
"release_immediately": false
}release_immediately: true if you want the blocked message to be released immediately upon a false_positive verdict, without waiting for human review.Receive the LLM verdict
The response includes the automated LLM verdict with a confidence score and reasoning:
{
"dispute_id": "dsp_f1g2h3-...",
"status": "reviewed",
"llm_verdict": "false_positive",
"llm_confidence": 0.91,
"llm_reasoning": "The pattern 123-45-6789 matches a US SSN format but appears in the context of a product serial number (SKU-123-45-6789). The surrounding text discusses inventory, not personal data.",
"message_released": false,
"tuning_suggestion": "tun_j4k5l6-..."
}Check dispute status
You can check the status of your disputes at any time:
GET /v1/guard/disputes
Authorization: Bearer cnk_grd_...
# Or get a specific dispute:
GET /v1/guard/disputes/{dispute_id}
Authorization: Bearer cnk_grd_...SOC Admin Human Review
SOC administrators can override the LLM verdict with a human review. This is useful when the LLM is uncertain (inconclusive) or when organizational context changes the interpretation of a finding.
POST /v1/guard/disputes/{dispute_id}/review
Authorization: Bearer <admin-jwt>
{
"verdict": "false_positive",
"release_message": true,
"notes": "Confirmed: this is a product serial number format used by our supplier"
}true_positive but the admin overrides to false_positive, a tuning suggestion is generated to prevent the same false positive in the future.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 |
| GET | /v1/guard/tuning/{id} | Get tuning suggestion details |
| POST | /v1/guard/tuning/{id}/apply | Apply the suggestion to the guardrail profile (org admin) |
| 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
(verdict: false_positive / true_positive / inconclusive)
|
+-- true_positive --> Dispute closed, block stands
|
+-- inconclusive --> Escalated for human review
|
+-- false_positive --> Tuning suggestion generated
|
v
SOC admin can override any verdict
|
v
Tuning suggestion: apply or reject
|
v
Guardrail profile updated (if applied)