Grounding API Documentation

Overview

The Grounding API accepts text containing marketing claims and returns per-claim verdicts (verified, corrected, disputed, unverifiable) with citations to the underlying Lighthouse statistics. Each citation includes the stat ID, metric, entity, source, data vintage, and confidence score.

Authentication

Production API calls require a valid API key in the X-API-Key header. The playground is free for evaluation without a key.

X-API-Key: lh_live_your_api_key_here

POST /grounding/api/verify

Request body:

{
  "text": "Email marketing ROI is 4200%. Social media engagement averages 3.5%."
}

Response (200):

{
  "text_length": 62,
  "claims_found": 2,
  "results": [
    {
      "claim_text": "4200% Email marketing ROI",
      "claim_value": 4200.0,
      "verdict": "verified",
      "correction": null,
      "difference_pct": 0.5,
      "citation": {
        "stat_id": "st_abc123",
        "metric": "email_marketing_roi",
        "entity": "industry_average",
        "source": "DMA National Client Email Report 2025",
        "vintage": "2025",
        "confidence": 0.92
      }
    }
  ]
}

Verdict values: verified (within 5% of corpus), corrected (within 15%), disputed (beyond 15%), unverifiable (no matching stat found).

Error Codes

Rate Limits

Free tier: 100 verifies/month. Starter: 100/month. Pro: 1,000/month. Business: 5,000/month. Enterprise: custom.

Examples

cURL:

curl -X POST https://lighthousedata.io/grounding/api/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lh_live_your_key" \
  -d '{"text": "Email ROI is 4200%"}'

Python:

import requests
resp = requests.post(
    "https://lighthousedata.io/grounding/api/verify",
    headers={"X-API-Key": "lh_live_your_key"},
    json={"text": "Email ROI is 4200%"}
)
print(resp.json())

JavaScript:

const resp = await fetch("https://lighthousedata.io/grounding/api/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "lh_live_your_key"
  },
  body: JSON.stringify({text: "Email ROI is 4200%"})
});
const data = await resp.json();
console.log(data);