Quickstart
Make a source-backed request. Then inspect the citations and retrieved sources.
What This Does
Madeenan retrieves Islamic sources, grounds the answer in those sources, and returns citation-ready payloads.
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 Dua of Yunus with sources"
}'
Minimal Response
{
"session_id": "7d7f7a9a-8a5f-4f42-b3db-1c9b5f2f2c30",
"answer": "The Dua of Yunus is a prayer of humility and repentance: 'There is no deity except You; exalted are You. Indeed, I have been of the wrongdoers.' The Qur'an mentions it in Surah al-Anbiya.",
"citations": [
{
"source_id": "quran_21_87",
"type": "quran",
"citation_label": "Qur'an 21:87",
"title": "Surah al-Anbiya",
"arabic": "لَا إِلَٰهَ إِلَّا أَنتَ سُبْحَانَكَ إِنِّي كُنتُ مِنَ الظَّالِمِينَ",
"translation": "There is no deity except You; exalted are You. Indeed, I have been of the wrongdoers."
}
],
"retrieved_sources": [
{
"source_id": "quran_21_87",
"type": "quran",
"citation_label": "Qur'an 21:87",
"title": "Surah al-Anbiya",
"arabic": "لَا إِلَٰهَ إِلَّا أَنتَ سُبْحَانَكَ إِنِّي كُنتُ مِنَ الظَّالِمِينَ",
"translation": "There is no deity except You; exalted are You. Indeed, I have been of the wrongdoers."
}
]
}
Fields Explained
message
The user prompt. Use natural language in English or Arabic.
indexes
Optional source families to search: Qur'an, Hadith, Tafsir, and dua.
citations
Sources you can render beside the answer: label, Arabic, translation, and metadata.
retrieved_sources
The source set used for grounding. Show it when users need more context.
Real Examples
Search first when you want source cards. For production generation, call your own LLM from your backend with the returned source blocks.
$curl "https://api.madeenan.com/v1/search?q=Dua%20of%20Yunus&indexes=quran,hadith,tafsir,dua&limit_per_source=3" \
-H "X-Madeenan-API-Key: mdeen_live_..."
const sources = await fetch("https://api.madeenan.com/v1/search?q=patience&indexes=quran,hadith,tafsir,dua", {
headers: { "X-Madeenan-API-Key": process.env.MADEENAN_API_KEY }
}).then((res) => res.json());
// Then call your own LLM provider from your backend using the returned
// source blocks as context. Do not send model provider keys to the browser.
Common Mistakes
- Sending model provider keys from the browser.
- Hiding required attribution on generated answers.
- Treating citations as optional UI metadata.
- Using chat when a direct Search API result is enough.
Security note
Keep Madeenan API keys and model provider keys on your server. Browser apps should call your backend, not provider APIs directly.