Quran and Hadith 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 sources grouped by corpus. Each result includes Arabic text, translation, reference, score, metadata, and 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 results per corpus. The API clamps values outside the supported range. |
Real Examples
Direct source reads are anonymous and cacheable. Use them when you know the exact reference.
$curl "https://api.madeenan.com/v1/quran/2:255"
$curl "https://api.madeenan.com/v1/quran/passage/94/5-6"
$curl "https://api.madeenan.com/v1/hadith/bukhari/1"
$curl "https://api.madeenan.com/v1/dua/hisn-al-muslim/121"
Quote Matching
Quote search checks wording against Qur'an, Hadith, and dua sources by default. The response keeps the match_type, confidence, matched_excerpt, and source fields.
The structured evidence report shows:
- how much of the quotation the source contains.
- token overlap and sequence similarity for close wording.
- the matched language and field.
- attribution text that was ignored.
- whether the match came from exact retrieval or semantic-only retrieval.
Typed related_sources list reviewed provenance where available. retrieval_status and ambiguity flag degraded or repeated results. Only normalized containment can produce an exact wording verdict.
$curl "https://api.madeenan.com/v1/quote-search" \
-H "Content-Type: application/json" \
-d '{"text":"Actions are judged by intentions"}'
Common Mistakes
- Using Search API output as a generated answer.
- Treating the confidence value as a probability.
- Dropping Arabic text when source display matters.
Source note
Search is best for source discovery. Chat is best for answer synthesis.