Search API
Search Qur'an, Hadith, Tafsir, and dua/adhkar sources before you generate, display, or cite an answer.
What This Does
Search returns ranked source records grouped by corpus, with Arabic text, translations, references, scores, metadata, and retrieval timings.
Minimal Request
$curl "https://api.madeenan.com/v1/search?q=آية%20الكرسي%20meaning&indexes=quran,hadith,tafsir,dua&limit_per_source=3" \
-H "X-Madeenan-API-Key: mdeen_live_..."
Minimal Response
{
"results": {
"quran": [
{
"id": "quran_2_255",
"type": "quran_verse",
"ref": "Qur'an 2:255",
"title": "Ayat al-Kursi",
"arabic": "اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ الْحَيُّ الْقَيُّومُ…",
"translation": "Allah - there is no deity except Him, the Ever-Living…",
"score": 1.0,
"metadata": {
"surah": 2,
"ayah": 255
}
}
],
"hadith": [],
"tafsir": [],
"dua": []
},
"request_id": "req_01h...",
"timings": {
"total_ms": 143
}
}
Fields Explained
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| q | string | Yes | — | The Arabic, English, or mixed-language query. |
| indexes | string | No | quran,hadith,tafsir,dua | Comma-separated corpora to search. Use quran, hadith, tafsir, dua, or any subset. |
| limit_per_source | integer | No | 12 | Maximum result count per requested source tab. The API clamps the value to the supported range. |
Real Examples
Use direct lookups when you already know the source coordinate.
$curl "https://api.madeenan.com/v1/quran/2:255" \
-H "X-Madeenan-API-Key: mdeen_live_..."
$curl "https://api.madeenan.com/v1/hadith/bukhari/1" \
-H "X-Madeenan-API-Key: mdeen_live_..."
Common Mistakes
- Using Search API output as a generated answer.
- Hiding low-confidence scores instead of asking users to refine.
- Dropping Arabic text when source display matters.
Source note
Search is best for source discovery. Chat is best for answer synthesis.