How to verify a hadith citation in code before it reaches a Muslim user.

Why the verification step exists

You are building an Islamic AI product. Your model produces an answer that cites a hadith. Before that answer reaches a Muslim user, you need to know: is the hadith real, is it sahih, is the attribution correct, and is the wording consistent with what is in the approved collections?

You cannot check this by prompting the model. The model that produced the citation is the same model that would verify it: the same training data, the same tendencies, the same blind spots. You need an independent system that checks against authoritative sources.

That is what Tasfi Guard does. It runs between your model and your user. You send it the answer. It checks the answer against the approved source bundle. It returns a verdict and a signed Trust Receipt.

The basic call

The verification endpoint accepts a POST with a JSON body. The minimum required fields are answer (the generated text to verify) and context (what was asked).

{
  "answer": "The Prophet (peace be upon him) said: 'Actions are judged by intentions.' This is narrated in Sahih Bukhari.",
  "context": "Explain the importance of intention in Islam.",
  "madhab": "hanafi"
}

The madhab field is optional. When provided, Guard applies that madhab's scope to any fiqh claims in the answer. When omitted, Guard verifies against the common ground shared by all four Sunni madhabs.

Reading the response

Guard returns a JSON object with a verdict, an array of flags, source metadata, and the signed receipt ID.

{
  "verdict": "pass",
  "flags": [],
  "sourceBundle": {
    "version": "1.0.0",
    "checksum": "sha256:a3f...",
    "sources": ["tanzil-quran-v1", "fawaz-bukhari-v1"]
  },
  "boundary": {
    "sahihOnly": true,
    "madhabs": ["hanafi", "maliki", "shafii", "hanbali"],
    "noFatwa": true,
    "noScholarReplacement": true
  },
  "receiptId": "rec_01abc...",
  "issuedAt": "2026-05-16T12:00:00Z"
}

A pass verdict means every Islamic claim in the answer verified against the approved source bundle within the stated policy. The receipt ID is the cryptographic identifier you can use to prove verification happened.

Handling a fail verdict

When verification fails, the response includes the specific flags that failed and, where available, a remediation suggestion.

{
  "verdict": "fail",
  "flags": [
    {
      "type": "hadith-attribution-mismatch",
      "evidence": "Narration not found in Sahih Bukhari under the stated topic",
      "severity": "high",
      "remediation": "The narration 'Actions are judged by intentions' is in Sahih Bukhari, Kitab Bad al-Wahy, Hadith 1. Verify the collection and book reference."
    }
  ],
  "receiptId": "rec_01def...",
  "issuedAt": "2026-05-16T12:00:01Z"
}

The hadith-attribution-mismatch flag means the narration content matched the corpus but the attribution (collection name, book, or hadith number) did not match exactly. Your product should not show the answer as-is. Options: regenerate with the corrected attribution in the prompt, show a fallback, or prompt the user to consult a scholar.

The full flag taxonomy

Guard raises flags in these categories. Each flag includes type, evidence, severity (high, medium, low), and remediation when one exists.

Integration pattern: verify before display

The recommended integration puts verification between your model call and your display layer. In pseudocode:

import { TasfiClient } from "@tasfi/sdk";

const tasfi = new TasfiClient({ apiKey: process.env.TASFI_API_KEY });

async function getVerifiedIslamicAnswer(question, madhab) {
  const modelAnswer = await yourModel.generate(question);

  const result = await tasfi.verify({
    answer: modelAnswer,
    context: question,
    madhab,
  });

  if (result.verdict === "fail") {
    return {
      shown: false,
      reason: "verification_failed",
      receiptId: result.receiptId,
    };
  }

  return {
    shown: true,
    answer: modelAnswer,
    receiptId: result.receiptId,
    verdict: result.verdict,
  };
}

The receipt ID travels with the answer through your system. When a user reports a problem, you can retrieve the receipt to understand exactly what was verified and what the source bundle found.

What Guard does not do

Guard verifies what can be verified against the approved source bundle. It does not rule on novel fiqh questions that are not addressed in the approved methodology documents. It does not adjudicate disagreements between scholarly positions that are both within the four madhab scope. It does not issue fatawa. Every Trust Receipt says so explicitly.

The boundary is not a limitation. It is the product's integrity. A Muslim builder who understands the boundary can use Guard with confidence. A builder who expects Guard to resolve contested scholarly questions will be disappointed. Guard clears the path of known errors; it does not replace the scholars who hold the tradition.

Inspecting receipts

Every receipt ID links to a verifiable receipt object at /v1/receipts/verify. A third party can confirm that verification happened, what the verdict was, and what source bundle version was consulted. This is the paper trail that lets Muslim builders prove their verification layer to users, scholars, and stakeholders.