{"openapi":"3.0.3","info":{"title":"Deterministic Hallucination Diff API","version":"1.0.0","description":"Fast first-pass RAG grounding filter that compares an LLM answer against source passages using deterministic token/bigram overlap, numeric verification, and proper-noun entity matching (catches unsupported numbers and names; does not judge abstract reasoning or paraphrase in deterministic mode). Typically under 5 ms in deterministic mode (use_ai_judge: false) with zero payload logging; when use_ai_judge: true is set, excerpts are sent to Cloudflare Workers AI (@cf/meta/llama-3.1-8b-instruct) for stateless inference without retention or training."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"HallucinationDiffResponse":{"type":"object","properties":{"grounded_score":{"type":"integer","minimum":0,"maximum":100,"example":65},"verdict":{"type":"string","enum":["grounded","partially_grounded","ungrounded"],"example":"partially_grounded"},"summary":{"type":"object","properties":{"total_claims":{"type":"integer","minimum":0},"supported_claims":{"type":"integer","minimum":0},"partial_claims":{"type":"integer","minimum":0},"unsupported_claims":{"type":"integer","minimum":0},"missing_numbers":{"type":"array","items":{"type":"string"}},"missing_entities":{"type":"array","items":{"type":"string"}}},"required":["total_claims","supported_claims","partial_claims","unsupported_claims","missing_numbers","missing_entities"]},"claims":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"text":{"type":"string"},"status":{"type":"string","enum":["supported","partial","unsupported"]},"overlap_score":{"type":"number","minimum":0,"maximum":1},"missing_numbers":{"type":"array","items":{"type":"string"}},"missing_entities":{"type":"array","items":{"type":"string"}},"evidence":{"type":"object","nullable":true,"properties":{"source_index":{"type":"integer","minimum":0},"quote":{"type":"string"}},"required":["source_index","quote"]}},"required":["index","text","status","overlap_score","missing_numbers","missing_entities","evidence"]}},"judge":{"type":"string","enum":["disabled","workers_ai","unavailable"],"example":"disabled"},"ai_judge":{"type":"object","nullable":true,"properties":{"flagged":{"type":"boolean"},"confidence":{"type":"number","minimum":0,"maximum":1},"reason":{"type":"string","nullable":true}},"required":["flagged","confidence","reason"]}},"required":["grounded_score","verdict","summary","claims"]},"HallucinationDiffRequest":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"maxLength":50000,"example":"Tinplate processes requests in 3 ms with 99.9% uptime and was founded in 2026 in Budapest.","description":"Generated LLM answer to verify against source documents."},"sources":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50000},"minItems":1,"maxItems":20,"example":["Tinplate is an edge API platform founded in 2026 in Budapest with latency typically under 5 ms in deterministic mode."],"description":"Grounding source passages or RAG chunks."},"strictness":{"type":"string","enum":["lenient","balanced","strict"],"example":"balanced","description":"Threshold profile for classifying claims as supported, partial, or unsupported."},"use_ai_judge":{"type":"boolean","example":false,"description":"Enable optional Cloudflare Workers AI second-pass semantic grounding judge (default false). When true, up to 4,000 chars of sources and 1,500 chars of answer are sent over Cloudflare's internal binding to @cf/meta/llama-3.1-8b-instruct (adds ~150-400 ms; zero model training or retention)."}},"required":["answer","sources"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/hallucination-diff":{"post":{"tags":["14_HALLUCINATION_DIFF"],"summary":"Check an LLM answer against grounding sources for unsupported claims","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HallucinationDiffRequest"}}}},"responses":{"200":{"description":"Groundedness score and per-claim diff","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/HallucinationDiffResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}