API

Base URL

https://api.komplexai.io/api

Send your API key as an Authorization: Bearer <key> header. Public sign-ups open at launch.

POST /detect

Runs hallucination detection on a single LLM response.

Request

{
  "response": "The Eiffel Tower was built in 1887 by Gustav Eiffel..."
}

Response

{
  "p_hallucination": 0.73,
  "flag": true,
  "top_regime": "FABRICATED",
  "regime_scores": [
    {"regime": "FABRICATED",    "p": 0.61},
    {"regime": "CF_AUTH",       "p": 0.18},
    {"regime": "NEAR_FALSE",    "p": 0.09},
    {"regime": "NORMAL",        "p": 0.06},
    {"regime": "Other",         "p": 0.05},
    {"regime": "FALSE_REFUSAL", "p": 0.01}
  ],
  "request_id": "req_a1b2c3d4e5f6a7b8",
  "detections_billed": 1,
  "mode": "short",
  "latency_ms": 210,
  "model_version": "nl-v1",
  "calibrator_version": "platt_v1:<cell>",
  "input_mode_used": "ro",
  "task_used": "multiclass",
  "warnings": []
}

Response fields

Warnings

The response body always carries a warnings: string[] field (usually []) with advisory codes the proxy attaches based on quota, subscription, and calibration state. Useful for surfacing "you're near your limit" in your app without polling /api/usage/summary.

Forward-compatibility: clients MUST ignore unknown codes. Future model / billing revisions may add codes here without bumping the API version.

Response headers

Every /detect response carries usage and rate-limit headers. Use them to track spend without polling /api/usage/summary.

Suggested thresholds

The wire response carries the raw p_hallucination and a convenience flag (server-side threshold; model-dependent, not a fixed 0.5). The bucket cuts below are demo-UI buckets only, not the server flag cut. Clients are free to pick their own thresholds.

Example — curl

curl -X POST https://api.komplexai.io/api/detect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HALU_API_KEY" \
  -d '{
    "response": "The Eiffel Tower is in Paris, France.",
    "prompt": "Where is the Eiffel Tower?",
    "task": "multiclass"
  }'

Example — Python

import halu

result = halu.detect(
    response="The Eiffel Tower is in Paris, France.",
    prompt="Where is the Eiffel Tower?",
    task="multiclass",
)
print(result.p_hallucination, result.flag, result.top_regime)

Example — JavaScript / TypeScript

const response = await fetch("https://api.komplexai.io/api/detect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.HALU_API_KEY}`,
  },
  body: JSON.stringify({
    response: "The Eiffel Tower is in Paris, France.",
    prompt: "Where is the Eiffel Tower?",
    task: "multiclass",
  }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Detect failed: ${err.error || err.detail}`);
}

const result = await response.json();
console.log(`p_hallucination: ${result.p_hallucination}`);
console.log(`flag: ${result.flag}`);
console.log(`top_regime: ${result.top_regime}`);

Use fetch in any JS/TS environment (Node, browser, Vercel, Cloudflare Workers, etc.). An official @komplexai/halu Node package is planned post-launch.

Caveats

• Input mode is auto-detected. The detector runs in prompt+response (pr) mode when prompt is non-empty, otherwise response-only (ro). In ro mode the detector never sees the prompt, so factual hallucinations that require prompt context may be missed — include the prompt for best accuracy when context matters.
• Probabilistic output. Scores are calibrated probabilities, not ground truth. See Performance for per-regime accuracy.
• Max 2,048 characters per field. Longer inputs are rejected with an input_too_long error (HTTP 400) — not truncated.
• English natural-language only. Code, structured output (JSON, XML), and non-English text are outside the trained range — see Scope above.

Rate limits

Free tier requires a key — sign up with Google to get one instantly. Free tier: 3,700 API requests/month plus 300 web-app detections/month. Higher limits via paid plan — see Pricing.