AletheionGuard API v1.1.0
Epistemic auditor for LLM outputs with Managed and BYO-HF modes
OAS 3.1 | /openapi.json
API Overview
Base URL
Production: https://aletheionguard.onrender.com
Authentication
Authorization: Bearer YOUR_API_KEYX-API-Key: YOUR_API_KEYAPI Endpoints
GET
/Root endpoint.
GET
/healthHealth check endpoint. No authentication required.
Response (200 OK)
{
"status": "string",
"version": "string",
"uptime_seconds": 0
}
POST
/v1/auditAudit a single LLM response. Supports both Managed and BYO-HF modes:
- Managed mode: Uses default HF_ENDPOINT_URL and HF_TOKEN from env
- BYO-HF mode: Uses X-HF-Token and X-HF-Endpoint headers from client
Headers (Optional - BYO-HF mode)
X-HF-Token: Your Hugging Face tokenX-HF-Endpoint: Your Hugging Face endpoint URLRequest Body
{
"text": "string",
"context": "string",
"model_source": "string"
}
Response (200 OK)
{
"q1": 0,
"q2": 0,
"height": 0,
"ece": 0,
"brier": 0,
"verdict": "string",
"confidence_interval": [
0
],
"explanation": "string",
"metadata": {
"additionalProp1": {}
},
"mode": "string",
"upstream_latency_ms": 0
}
Response (422 Validation Error)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Raises: HTTPException 400 if invalid endpoint, 502 if HF upstream fails, 500 if audit fails
POST
/v1/batchAudit multiple responses in batch.
Request Body
{
"items": [
{
"text": "string",
"context": "string",
"model_source": "string"
}
]
}
Response (200 OK)
{
"audits": [
{
"q1": 0,
"q2": 0,
"height": 0,
"ece": 0,
"brier": 0,
"verdict": "string",
"confidence_interval": [
0
],
"explanation": "string",
"metadata": {
"additionalProp1": {}
},
"mode": "string",
"upstream_latency_ms": 0
}
],
"summary": {
"additionalProp1": {}
}
}
Response (422 Validation Error)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
POST
/v1/compareCompare calibration quality across multiple model outputs. Ranks models by epistemic uncertainty (Q2) and calibration metrics. Lower Q2 = more confident/reliable prediction.
Request Body
{
"prompt": "string",
"responses": [
{
"additionalProp1": {}
},
{
"additionalProp1": {}
}
]
}
Response (200 OK)
{
"prompt": "string",
"comparisons": [
{
"additionalProp1": {}
}
],
"ranking": [
{
"additionalProp1": {}
}
],
"best_model": "string",
"summary": {
"additionalProp1": {}
}
}
Response (422 Validation Error)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Raises: HTTPException 400 if invalid input, 500 if comparison fails
POST
/v1/calibratePerform audit with optional online calibration feedback. Supports optional ground truth or human feedback for online learning. Future versions will use this feedback to improve calibration.
Request Body
{
"text": "string",
"context": "string",
"ground_truth": 1,
"feedback": "string"
}
Response (200 OK)
{
"q1": 0,
"q2": 0,
"height": 0,
"verdict": "string",
"calibration_adjustment": 0,
"feedback_recorded": false
}
Response (422 Validation Error)
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Raises: HTTPException 500 if calibration fails
Code Examples
cURL
curl -X POST https://aletheionguard.onrender.com/v1/audit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Paris is the capital of France"}'
Python
import requests
url = "https://aletheionguard.onrender.com/v1/audit"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {"text": "Paris is the capital of France"}
response = requests.post(url, headers=headers, json=data)
print(response.json())
JavaScript (Node.js)
const response = await fetch('https://aletheionguard.onrender.com/v1/audit', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({text: 'Paris is the capital of France'})
})
const data = await response.json()
console.log(data)
Need Help with the API?
Our team is here to help you integrate AletheionGuard