The Grounded API lets you run hallucination checks programmatically — from CI/CD pipelines, test frameworks, or your own applications. You send a question and an AI response. Grounded returns a GR score, a risk verdict, and per-layer breakdown.
Same 9-layer pipeline
Identical to the dashboard
JSON response
Machine-readable, easy to parse
Usage tracked
Counts against your monthly plan
Beta: The API is in beta. Endpoints and response shapes may change. Pin to v1 and monitor the changelog.
Authentication
All API requests require a Bearer token in the Authorization header. Generate your API key from the dashboard under API Keys.
HTTP
POST /api/v1/detect
Authorization: Bearer grnd_your_api_key_here
Content-Type: application/json
Keep your key secret. API keys are shown once at creation. Store them in environment variables, never in source code. Revoke compromised keys immediately from the dashboard.
POST /api/v1/detect
Runs the full 9-layer hallucination check on an AI response and returns a GR score and structured findings.
REQUEST BODY
PARAMETERTYPEDESCRIPTION
questionstringrequiredThe prompt or question sent to the AI.
ai_responsestringrequiredThe AI-generated response you want to test.
reference_docstringoptionalOptional reference document for grounding check. Paste your policy, spec, or knowledge base text.
structured_datastringoptionalOptional CRM or structured data (CSV or JSON). Enables the 9th layer — Structured Data Fidelity. Grounded type-detects every field, computes aggregates, and verifies every AI claim against your actual data.
EXAMPLE REQUEST
JSON
{
"question": "What is the average days open for SLA breached tickets?",
"ai_response": "SLA breached tickets average 14.5 days open across 8 tickets.",
"reference_doc": "Optional: paste a policy or knowledge base document here.",
"structured_data": "ticket_id,days_open,sla_breach\nT-001,14,true\nT-002,5,false\nT-003,20,true"
}
Response format
JSON
{
"score": 38,
"risk": "HIGH",
"gr": "GR-1",
"industry": "finance",
"industries_detected": ["finance", "hr"],
"layers": {
"consistency": { "score": 45 },
"grounding": { "score": 12, "skipped": false },
"confidence": { "score": 60, "suspicious_claims": ["8% for all employees"] },
"model_agreement": { "score": 30, "skipped": false, "note": "GPT-4o states 11.5%, not 8%" },
"semantic_drift": { "score": 90 },
"domain_rules": {
"score": 40,
"findings": 1,
"violations": [{
"type": "incorrect_sg_rate",
"detail": "Superannuation guarantee rate stated as 8% — incorrect.",
"correct_answer": "The SG rate is 11.5% from 1 July 2024 (rising to 12% in 2025).",
"source": "ATO — Super guarantee percentage"
}]
},
"custom_rules": { "score": 100, "findings": 0, "violations": [] }
},
"recommendations": [{
"layer": "finance",
"issue": "Superannuation guarantee rate stated as 8% — incorrect.",
"correct_answer": "The SG rate is 11.5% from 1 July 2024."
}],
"meta": {
"model": "grounded-v1",
"timestamp": "2026-03-20T09:15:00.000Z",
"usage": { "used": 12, "limit": 500 }
}
}
RESPONSE FIELDS
scoreintegeroptionalOverall hallucination risk score 0–100. Higher is better.
riskstringoptionalLOW (≥76), MED (≥60), or HIGH (<60).
industrystringoptionalPrimary detected industry (healthcare, legal, finance, etc.).
industries_detectedarrayoptionalAll industries detected in the question/response.
layersobjectoptionalPer-layer scores and findings. Skipped layers have skipped: true.
recommendationsarrayoptionalActionable fixes for domain/custom rule violations found.
meta.usageobjectoptionalCurrent month run count and your plan limit.
Error codes
401unauthorizedMissing, invalid, or revoked API key.
400bad_requestquestion or ai_response missing or empty.
429limit_exceededMonthly run limit reached. Upgrade your plan.
500internal_errorSomething went wrong on our end. Retry after a moment.
Code examples
cURL
BASH
curl -X POST https://grounded-topaz.vercel.app/api/v1/detect \
-H "Authorization: Bearer grnd_your_key" \
-H "Content-Type: application/json" \
-d '{
"question": "What is the CGT rate in Australia?",
"ai_response": "Australia has a flat CGT rate of 25%."
}'
Python
PYTHON
import requests
response = requests.post(
"https://grounded-topaz.vercel.app/api/v1/detect",
headers={"Authorization": "Bearer grnd_your_key"},
json={
"question": "What is the CGT rate in Australia?",
"ai_response": "Australia has a flat CGT rate of 25%."
}
)
result = response.json()
print(f"GR Rating: {result['gr']} — Score: {result['score']}/100")
print(f"Risk: {result['risk']}")
if result.get("recommendations"):
for rec in result["recommendations"]:
print(f"Fix: {rec['correct_answer']}")
Node.js
JAVASCRIPT
const response = await fetch("https://grounded-topaz.vercel.app/api/v1/detect", {
method: "POST",
headers: {
"Authorization": "Bearer grnd_your_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
question: "What is the CGT rate in Australia?",
ai_response: "Australia has a flat CGT rate of 25%.",
}),
});
const result = await response.json();
// Block CI/CD if risk is HIGH
if (result.risk === "HIGH") {
console.error(`Hallucination detected: GR ${result.gr} (${result.score}/100)`);
process.exit(1);
}
CI/CD gate (GitHub Actions)
YAML
- name: Hallucination check
run: |
RESULT=$(curl -s -X POST \
https://grounded-topaz.vercel.app/api/v1/detect \
-H "Authorization: Bearer ${{ secrets.GROUNDED_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"question":"$Q","ai_response":"$A"}')
RISK=$(echo $RESULT | jq -r '.risk')
if [ "$RISK" = "HIGH" ]; then
echo "❌ AI response failed hallucination check"
exit 1
fi
echo "✅ GR rating: $(echo $RESULT | jq -r '.gr')"
env:
Q: "What is our return policy?"
A: "${{ steps.ai-response.outputs.text }}"
Rate limits & plans
PLANRUNS/MONTHNOTES
TESTER50Free forever. Dashboard + API.
STARTER500$29/month. Suitable for solo consultants.
TEAM5,000$149/month. For QA teams.
ENTERPRISEUnlimitedCustom pricing. Contact us.
API usage counts against the same monthly quota as dashboard usage. The meta.usage field in every response shows your current count and limit. When the limit is reached, the API returns HTTP 429.