Shield API

The Shield API lets you manage verified facts (truth nuggets), monitor detected hallucinations, and manage fact-checking alerts.

Overview

Shield provides:

Truth Nuggets — Curated verified facts
Alerts — Hallucination and accuracy warnings
Corrections — Deployed fact corrections

Truth Nuggets

Create Truth Nugget

POST /api/v1/nuggets

A truth nugget is a verified fact about your domain:

curl -X POST https://api.truthvouch.com/api/v1/nuggets \
  -H "Authorization: Bearer tv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fact": "Our API handles 1 million requests per second",
    "context": "Product specifications",
    "sources": [
      {
        "title": "Performance Benchmark",
        "url": "https://blog.company.com/benchmarks/2024"
      }
    ],
    "tags": ["product", "performance"],
    "verified": true
  }'

List Truth Nuggets

GET /api/v1/nuggets

curl "https://api.truthvouch.com/api/v1/nuggets?tag=product&page=1" \
  -H "Authorization: Bearer tv_live_..."

Get Nugget

GET /api/v1/nuggets/{nuggetId}

curl https://api.truthvouch.com/api/v1/nuggets/nugget_abc123 \
  -H "Authorization: Bearer tv_live_..."

Alerts

Get Alerts

GET /api/v1/alerts

curl "https://api.truthvouch.com/api/v1/alerts?severity=high&status=open" \
  -H "Authorization: Bearer tv_live_..."

Response:

{
  "data": [
    {
      "id": "alert_123",
      "severity": "high",
      "type": "hallucination",
      "message": "Response contains unverified claim about product specifications",
      "fact": "Our API handles 100M requests per second",
      "actualFact": "Our API handles 1M requests per second",
      "confidenceScore": 0.92,
      "status": "open",
      "createdAt": "2024-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 42
  }
}

Resolve Alert

PATCH /api/v1/alerts/{alertId}

curl -X PATCH https://api.truthvouch.com/api/v1/alerts/alert_123 \
  -H "Authorization: Bearer tv_live_..." \
  -d '{
    "status": "resolved",
    "resolution": "Hallucination - LLM was hallucinating, corrected model version"
  }'

Corrections

Corrections are fact updates deployed after hallucinations are detected.

Create Correction

POST /api/v1/corrections

curl -X POST https://api.truthvouch.com/api/v1/corrections \
  -H "Authorization: Bearer tv_live_..." \
  -d '{
    "alertId": "alert_123",
    "correctFact": "Our API handles 1 million requests per second",
    "reason": "LLM was hallucinating higher numbers",
    "source": "Product documentation, verified by engineering team"
  }'

Deploy Correction

Once a correction is reviewed, deploy it:

PATCH /api/v1/corrections/{correctionId}

curl -X PATCH https://api.truthvouch.com/api/v1/corrections/correction_xyz \
  -H "Authorization: Bearer tv_live_..." \
  -d '{
    "status": "deployed"
  }'

Alert Types

Type	Description
`hallucination`	Claim contradicts known facts
`unverified_claim`	No sources found to verify
`source_conflict`	Sources disagree on fact
`outdated_info`	Fact is outdated
`contextual_error`	Correct fact, wrong context

Alert Severity

Severity	Impact	Recommended Action
`critical`	High confidence hallucination	Immediate correction needed
`high`	Strong evidence of error	Review and correct promptly
`medium`	Moderate confidence issue	Review when possible
`low`	Potential issue, needs review	Investigate if recurring

Severity thresholds are configurable in Settings → Alert Rules.