Which Hadith collections does the API cover?

Sahih al-Bukhari, Sahih Muslim, Sunan Abu Dawud, Jami at-Tirmidhi, Sunan an-Nasa'i, and Sunan Ibn Majah, in Arabic and English.

Can I return only sahih Hadith?

Yes. Add hadith_grade=sahih to a search request, or hadith_grade=sahih,hasan to include both groups. Without a grade filter, search leaves out reports graded fabricated or denounced.

Does the API verify whether a Hadith is authentic?

No. It returns the grade recorded by the source edition where one exists. It does not grade reports or issue rulings. Quote search shows where wording appears, which is not the same as authenticity.

Is the Hadith API free?

Report lookups and quote search do not need an API key. Search works on the free tier with a daily limit. The Starter plan is $5 per month for 3,000 searches, and the API plan is $39 per month for 30,000 searches.

Can I search Quran and Hadith together?

Yes. Set indexes=quran,hadith, or leave indexes out to search Quran, Hadith, Tafsir, and duas. Results come back grouped by corpus.

How do I cite a Hadith result?

Show the reference and collection, the grade with its source, and the Arabic text when you have space. Each result includes these fields so the reader can check the report.

Hadith API

Hadith API With Grades, Search, and Citations

Look up a report by collection and number, or search six major collections by meaning or wording. Filter by grade, and return the Arabic text, English translation, reference, and grade metadata your users need to check a source.

Read the Search Docs View API Plans

Collections: Bukhari, Muslim, Abu Dawud, Tirmidhi, Nasa'i, and Ibn Majah
Indexed Reports: 34,455 in the published search baseline
Grades: Grade text from the source edition where available, plus a grade filter
Access: Report lookups are public. Search works anonymously within free limits or with an API key.

Look Up a Report by Its Number

GET /v1/hadith/{collection}/{number} returns one report. The collection slugs are bukhari, muslim, abudawud, tirmidhi, nasai, ibnmajah. GET /v1/hadith/bukhari/1 returns the first report in Sahih al-Bukhari.

The response includes the reference, Arabic text, English translation, grade where the source edition records one, and collection metadata.

Search That Respects Grades

Users rarely know a report's number. They remember a phrase or a topic. GET /v1/search with indexes=hadith searches by meaning and wording together.

Add hadith_grade=sahih or hadith_grade=sahih,hasan to limit results to those grade groups. Add hadith_source_book to search one collection. Without a grade filter, search leaves out reports graded fabricated (mawdu') or denounced (munkar).

Check Where a Quote Comes From

A saying shared on social media often arrives with 'the Prophet said' and no reference. POST /v1/quote-search compares the wording with Hadith, Qur'an, and dua sources. It returns a match type, the matched excerpt, the source, and evidence about how much of the quote the source contains.

A wording match tells you where similar words appear. It does not establish that a report is authentic, and the response does not claim that it does.

Grades Come From the Source, Not From Us

Madeenan records the grade that the source edition gives. It does not issue its own grading, and some reports have no grade in the data. Scholars can differ on a grade, so show the grade with its source and avoid presenting it as a final verdict.

The Hadith text and grades are built from public editions, including the community hadith-api project. Each response keeps the reference so readers can check it against the printed collection.

Endpoints

All endpoints live under https://api.madeenan.com. Send an API key in the X-Madeenan-API-Key header from your server. The full schema is in the API reference.

Endpoint	Access	Use
GET /v1/hadith/{collection_slug}/{hadith_number}	Public	One report with grade metadata.
GET /v1/search	Anonymous or API key	Search with indexes=hadith, hadith_grade, and hadith_source_book.
POST /v1/quote-search	Public	Find where wording appears, with match evidence.
GET /v1/dua/{collection_slug}/{item_id}	Public	One dua or adhkar item, for example hisn-al-muslim/121.
POST /v1/chat	API key	Hosted answer generation with citations.

Examples

The TypeScript and Python clients are prepared for npm and PyPI but are not published yet. Until they are, call the REST endpoints directly; they are plain HTTPS and JSON.

Read a Report

No key needed. The response includes grade metadata where the edition has it.

$curl "https://api.madeenan.com/v1/hadith/bukhari/1"

Search Sahih and Hasan Reports

Send the API key from your server, not from a browser.

$curl "https://api.madeenan.com/v1/search?q=kindness%20to%20neighbours&indexes=hadith&hadith_grade=sahih,hasan&limit_per_source=5" \

-H "X-Madeenan-API-Key: $MADEENAN_API_KEY"

Check a Quote

Quote search accepts 8 to 2,000 characters.

$curl "https://api.madeenan.com/v1/quote-search" \

-H "Content-Type: application/json" \

-d '{"text":"Actions are judged by intentions","indexes":["hadith"]}'

TypeScript

The typed client accepts the same grade filter.

import { MadeenanClient } from "@madeenan/sdk";

const client = new MadeenanClient({

apiKey: process.env.MADEENAN_API_KEY,

});

const results = await client.search({

q: "actions are judged by intentions",

indexes: ["hadith"],

hadith_grade: "sahih,hasan",

limit_per_source: 5,

});

for (const source of results.results.hadith ?? []) {

console.log(source.ref, source.grade);

}

const report = await client.hadith("bukhari", 1);

console.log(report.ref, report.grade);

What It Does Not Do

Six collections today. Musnad Ahmad, Muwatta Malik, and other collections are not indexed yet.
Arabic and English only.
Grades come from the source edition. Madeenan does not grade reports, and some reports have no grade.
Quote search finds matching wording. It does not authenticate a report.

How It Compares

The right Hadith data source depends on whether you need bulk files, search, or full control. This table compares the common options.

Need	Madeenan	fawazahmed0/hadith-api	Self-Hosted Hadith Dataset
Built For	Search, grade filters, and citation payloads	Free bulk access to editions in many languages	Full control over data, ranking, and hosting
Lookup by Number	Yes	Yes, per edition	You build it
Search	Meaning and keyword search with filters	No search endpoint; static JSON files	You build and tune it
Grades	Grade text where available, plus a grade filter	Grades included in the data	Depends on the dataset
Languages	Arabic and English	Many languages	Depends on the dataset
Quran, Tafsir, and Duas	Same API and result shape	Separate projects	Separate work
Access	Public lookups; API key for search volume and chat	No key; served from the jsDelivr CDN	Your own infrastructure
Cost	Free tier; paid plans from $5 per month	Free, Unlicense	Hosting and maintenance time

Checked in October 2026 against each project's public documentation. If you only need to display reports you already know, a static dataset is simpler. Madeenan helps when users search by topic or wording.

Sources: fawazahmed0/hadith-api on GitHub

Plans and Limits

Lookups are public. Search and hosted chat count against your plan. You pay any model provider you call from your own backend directly.

Free

$0 per month

10 searches/day
No hosted chat
No API key access
Source search for evaluation

Starter

$5 per month

3,000 searches/month
API key access
Source retrieval and citation payloads
100 hosted chat answers/month
60 requests per minute per key

API / Organization

$39 per month

30,000 searches/month included
API key access
Source retrieval and citation payloads
500 hosted chat answers/month
For B2B product integration
120 requests per minute per key

See pricing for current plans and rate limits for retry guidance.

Questions Developers Ask

Which Hadith collections does the API cover?: Sahih al-Bukhari, Sahih Muslim, Sunan Abu Dawud, Jami at-Tirmidhi, Sunan an-Nasa'i, and Sunan Ibn Majah, in Arabic and English.
Can I return only sahih Hadith?: Yes. Add hadith_grade=sahih to a search request, or hadith_grade=sahih,hasan to include both groups. Without a grade filter, search leaves out reports graded fabricated or denounced.
Does the API verify whether a Hadith is authentic?: No. It returns the grade recorded by the source edition where one exists. It does not grade reports or issue rulings. Quote search shows where wording appears, which is not the same as authenticity.
Is the Hadith API free?: Report lookups and quote search do not need an API key. Search works on the free tier with a daily limit. The Starter plan is $5 per month for 3,000 searches, and the API plan is $39 per month for 30,000 searches.
Can I search Quran and Hadith together?: Yes. Set indexes=quran,hadith, or leave indexes out to search Quran, Hadith, Tafsir, and duas. Results come back grouped by corpus.
How do I cite a Hadith result?: Show the reference and collection, the grade with its source, and the Arabic text when you have space. Each result includes these fields so the reader can check the report.