madeenan

Chat API

Generate an answer grounded in Qur'an, Hadith, Tafsir, and dua/adhkar sources, with citations returned in the response.

What This Does

Chat retrieves sources, builds grounded model context, calls Madeenan's hosted Gemini Flash-Lite path, and returns the answer plus source blocks.

Minimal Request

$curl https://api.madeenan.com/v1/chat \
-H "X-Madeenan-API-Key: mdeen_live_..." \
-H "Content-Type: application/json" \
-d '{
"message": "Explain the hadith: actions are by intentions",
"limit": 8,
"indexes": ["quran", "hadith", "tafsir", "dua"]
}'

Minimal Response

{
"session_id": "f3eb4d6e-9c7f-4f6b-a044-8df6f4df1c4d",
"answer": "The hadith teaches that deeds are judged by the intention behind them. It is foundational for worship, ethics, and sincerity.",
"citations": [
{
"source_id": "hadith_bukhari_1",
"type": "hadith",
"citation_label": "Sahih al-Bukhari 1",
"title": "Actions are by intentions",
"arabic": "إِنَّمَا الأَعْمَالُ بِالنِّيَّاتِ…",
"translation": "Actions are but by intentions…",
"grade": "Sahih"
}
],
"provider": "gemini",
"model": "gemini-2.5-flash-lite"
}

Fields Explained

FieldTypeRequiredDefaultNotes
messagestringYes—The user prompt. Use this field for chat requests.
session_idUUIDNo—Attach the request to an existing chat session.
streambooleanNofalseReturn server-sent chunks instead of waiting for the full answer.
indexesstring[]Noquran,hadith,tafsir,duaLimit retrieval to selected corpora: quran, hadith, tafsir, and dua.

Real Examples

const response = await fetch("https://api.madeenan.com/v1/chat", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Madeenan-API-Key": process.env.MADEENAN_API_KEY
},
body: JSON.stringify({
message: "Explain charity with sources",
stream: true
})
});
for await (const chunk of response.body) {
console.log(new TextDecoder().decode(chunk));
}
$curl https://api.madeenan.com/v1/feedback \
-H "X-Madeenan-API-Key: mdeen_live_..." \
-H "Content-Type: application/json" \
-d '{
"message_id": "a4af3c65-1f98-4df8-a936-0f1d2b7d2f2c",
"rating": "positive",
"comment": "Clear answer and useful citations."
}'

Common Mistakes

  • Sending query instead of message.
  • Sending model provider keys from a browser client.
  • Rendering the answer without citations or attribution.
  • Assuming citations are optional when showing generated Islamic answers.

Model/provider note

For production apps that need direct model control, call /v1/search, pass the returned source blocks to your own LLM from your backend, and render Madeenan citations beside the answer.