POST
/api/v1/firewall/groundRun the grounding / hallucination guardrail against an answer
Live grounding rail: checks a model answer against its retrieved sources under the tenant's grounding policy, then STRIPs / regrounds / blocks the ungrounded spans and signs every non-clean event into the crypto evidence-ledger. Per-request enforcement overrides (onFailAction, thresholds, failMode) apply to THIS check only.
Authentication
Send Authorization: Bearer YOUR_API_KEY on every request. Generate API keys at /dashboard/api-keys.
Request body required
Example
{
"question": "<The user query the answer responds to.>",
"sources": [],
"answer": "<The model answer to check / strip / regr>",
"orgId": "00000000-0000-0000-0000-000000000000",
"projectId": "00000000-0000-0000-0000-000000000000",
"onFailAction": "strip_ungrounded",
"minGroundedFraction": 0,
"riskThreshold": 0,
"failMode": "open"
}Schema
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "The user query the answer responds to."
},
"sources": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100000
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 200
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 100000
}
},
"required": [
"text"
],
"additionalProperties": false
}
]
},
"description": "Retrieved context the answer must be grounded in (>=1 passage)."
},
"answer": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "The model answer to check / strip / reground / block."
},
"orgId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Optional — tenant resolution / telemetry (membership verified by the API handler)."
},
"projectId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Optional — tenant resolution / telemetry (membership verified by the API handler)."
},
"onFailAction": {
"type": "string",
"enum": [
"strip_ungrounded",
"reground",
"block",
"warn",
"allow"
],
"description": "Per-request enforcement override (wins over the tenant policy for this check only)."
},
"minGroundedFraction": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"riskThreshold": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"failMode": {
"type": "string",
"enum": [
"open",
"closed"
]
}
},
"required": [
"question",
"sources",
"answer"
],
"additionalProperties": false
}
}
}Response
200 example
{
"success": true
}All status codes
200Grounding verdict (decision, groundedFraction, riskScore, strippedOutput, blocked, incidentId).
400(no description)
401(no description)
429(no description)
Code samples
cURL
curl -X POST \
https://evalguard.ai/api/v1/firewall/ground \
-H "Authorization: Bearer $EVALGUARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "question": "<The user query the answer responds to.>", "sources": [], "answer": "<The model answer to check / strip / regr>", "orgId": "00000000-0000-0000-0000-000000000000", "projectId": "00000000-0000-0000-0000-000000000000", "onFailAction": "strip_ungrounded", "minGroundedFraction": 0, "riskThreshold": 0, "failMode": "open" }'TypeScript
import { EvalGuard } from "@evalguard/sdk";
const client = new EvalGuard({ apiKey: process.env.EVALGUARD_API_KEY });
const response = await client.request({
method: "POST",
path: "/api/v1/firewall/ground",
body: {
"question": "<The user query the answer responds to.>",
"sources": [],
"answer": "<The model answer to check / strip / regr>",
"orgId": "00000000-0000-0000-0000-000000000000",
"projectId": "00000000-0000-0000-0000-000000000000",
"onFailAction": "strip_ungrounded",
"minGroundedFraction": 0,
"riskThreshold": 0,
"failMode": "open"
},
});
console.log(response);Python
from evalguard import EvalGuard
import os
client = EvalGuard(api_key=os.environ["EVALGUARD_API_KEY"])
response = client.request(
method="POST",
path="/api/v1/firewall/ground",
body={
"question": "<The user query the answer responds to.>",
"sources": [],
"answer": "<The model answer to check / strip / regr>",
"orgId": "00000000-0000-0000-0000-000000000000",
"projectId": "00000000-0000-0000-0000-000000000000",
"onFailAction": "strip_ungrounded",
"minGroundedFraction": 0,
"riskThreshold": 0,
"failMode": "open"
},
)
print(response)Go
package main
import (
"context"
"fmt"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{"question":"<The user query the answer responds to.>","sources":[],"answer":"<The model answer to check / strip / regr>","orgId":"00000000-0000-0000-0000-000000000000","projectId":"00000000-0000-0000-0000-000000000000","onFailAction":"strip_ungrounded","minGroundedFraction":0,"riskThreshold":0,"failMode":"open"}`)
req, _ := http.NewRequestWithContext(context.Background(), "POST", "https://evalguard.ai/api/v1/firewall/ground", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("EVALGUARD_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
fmt.Println(resp.Status)
}Errors
400401429