Hadeeth API
A free JSON API for the Arabic text, matn and isnād, of 17 classical hadith collections. You don't need a key to start.
https://hadeeth.rayan-app.comQuick start
Every endpoint is a plain GET that returns JSON. Successful responses wrap the payload in data, and lists add a meta object.
curl https://hadeeth.rayan-app.com/v1/books/bukhari/hadiths/1const res = await fetch("https://hadeeth.rayan-app.com/v1/books/bukhari/hadiths/1");
const { data } = await res.json();
console.log(data.arabic);import requests
r = requests.get("https://hadeeth.rayan-app.com/v1/books/bukhari/hadiths/1")
print(r.json()["data"]["arabic"])Response:
{
"data": {
"book": "bukhari",
"hadith_no": 1,
"chapter": { "index": 1, "title_ar": "كتاب بدء الوحى" },
"arabic": "حَدَّثَنَا الْحُمَيْدِيُّ عَبْدُ اللَّهِ بْنُ الزُّبَيْرِ ، قَالَ : حَدَّثَنَا سُفْيَانُ …"
}
}
Authentication
You don't need a key. Anonymous requests are limited per IP address. For higher limits, ask for an API key and send it in a header:
curl -H "Authorization: Bearer fq_your_key" https://hadeeth.rayan-app.com/v1/books
# or
curl -H "X-API-Key: fq_your_key" https://hadeeth.rayan-app.com/v1/books
?api_key= are rejected with 400, so keys don't leak into logs and browser history. An invalid or revoked key returns 401; it is never silently treated as anonymous.Rate limits
| Access | Per minute | Per day |
|---|---|---|
| No key (per IP) | 30 | 1,000 |
| Free key | 120 | 20,000 |
| Pro key | 600 | 250,000 |
Each request costs 1 unit, except search, which costs 5. The per-minute limit is a token bucket that refills continuously, so short bursts are fine. Daily limits reset at 00:00 UTC.
Every limited response includes these headers:
| RateLimit-Limit | Per-minute budget |
| RateLimit-Remaining | Units left in the current bucket |
| RateLimit-Reset | Seconds until the bucket is full again |
| X-RateLimit-Daily-Limit | Daily budget |
| X-RateLimit-Daily-Remaining | Units left today |
| Retry-After | Only on 429: seconds to wait before retrying |
Pagination
Lists return up to limit items (default 20, maximum 100). When there are more, meta.next_cursor holds a value; pass it back as cursor to get the next page. When it is null, you've reached the end.
GET /v1/books/nawawi40/hadiths?limit=20
→ "meta": { "next_cursor": "20", "total": 42 }
GET /v1/books/nawawi40/hadiths?limit=20&cursor=20
→ "meta": { "next_cursor": "40", "total": 42 }
Errors
Every error has the same shape:
{ "error": { "code": "unknown_book", "message": "unknown book; see /v1/books" } }
| Status | Codes | Meaning |
|---|---|---|
| 400 | bad_param bad_number bad_query key_in_query | The request is malformed |
| 401 | invalid_key | The API key is unknown or revoked |
| 404 | not_found unknown_book | No such hadith, collection or endpoint |
| 429 | rate_limited | Slow down; see Retry-After |
| 5xx | internal timeout | Our fault; retry with backoff |
Caching
The dataset changes rarely. Responses carry an ETag and Cache-Control: public, max-age=3600. Send the ETag back in If-None-Match; a 304 Not Modified response doesn't count against your limits.
Endpoints
Lists all collections with their hadith counts.
Lists a collection's chapters (كتب / أبواب) in order, with the range of hadith numbers in each.
Pages through a collection in hadith-number order.
| Param | Description |
|---|---|
| limit | 1–100, default 20 |
| cursor | The meta.next_cursor value from the previous page |
Returns one hadith by its number in the collection.
Full-text search across the Arabic text. Matching ignores diacritics (tashkīl), tatweel and hamza/alif variants, so انما الاعمال finds إِنَّمَا الْأَعْمَالُ. Every word must appear, and the last word also matches as a prefix. Single letters are ignored. Results are ranked by relevance (BM25). meta.total counts up to 1,000 matches; above that, meta.total_exact is false.
| Param | Description |
|---|---|
| qrequired | 2–200 characters |
| book | Limit results to one collection (slug) |
| limit | 1–100, default 20 |
| cursor | Offset from meta.next_cursor (up to 1000) |
Returns a random hadith, chosen uniformly from all collections or from one with ?book=. Responses are not cached.
Returns dataset totals, hadith counts per collection, and the data_version hash.
Collections
| Slug | Collection | Compiler | Hadiths |
|---|---|---|---|
bukhari | صحيح البخاري | الإمام محمد بن إسماعيل البخاري | 7,277 |
muslim | صحيح مسلم | الإمام مسلم بن الحجاج القشيري النيسابوري | 7,459 |
nasai | سنن النسائي | الإمام أبو عبد الرحمن أحمد بن شعيب النسائي | 5,768 |
abudawud | سنن أبي داود | الإمام سليمان بن الأشعث أبو داود السجستاني | 5,276 |
tirmidhi | جامع الترمذي | الإمام أبو عيسى محمد بن عيسى الترمذي | 4,053 |
ibnmajah | سنن ابن ماجه | الإمام محمد بن يزيد بن ماجه القزويني | 4,345 |
malik | موطأ مالك | الإمام مالك بن أنس | 1,860 |
ahmed | مسند الإمام أحمد بن حنبل | الإمام أحمد بن حنبل | 1,374 |
darimi | سنن الدارمي | الإمام أبو محمد عبد الرحمن بن عبد الله بن الدارمي | 3,406 |
nawawi40 | الأربعون النووية | الإمام يحيى بن شرف النووي | 42 |
qudsi40 | الأربعون القدسية | 40 | |
shahwaliullah40 | أربعون ولي الله الدهلوي | الشاه ولي الدين الدهلوي | 40 |
riyad_assalihin | رياض الصالحين | الإمام يحيى بن شرف النووي | 1,896 |
mishkat_almasabih | مشكاة المصابيح | الإمام الكاتب التبريزي | 4,428 |
aladab_almufrad | الأدب المفرد | الإمام محمد بن إسماعيل البخاري | 1,326 |
shamail_muhammadiyah | الشمائل المحمدية | الإمام الترمذي | 402 |
bulugh_almaram | بلوغ المرام | الإمام ابن حجر العسقلاني | 1,767 |
Objects
Hadith
| book | string | Collection slug |
| hadith_no | integer | Number within the collection |
| chapter.index | integer | 1-based chapter position in the collection |
| chapter.title_ar | string | Chapter title |
| arabic | string | Full Arabic text (isnād + matn) with diacritics |
| score | number | Search results only; higher is more relevant |
Book
| id | integer | Stable numeric id |
| slug | string | Used in URLs |
| name_ar | string | Collection title |
| author_ar | string | Compiler |
| hadith_count | integer | Number of hadiths |
Chapter
| index | integer | 1-based position |
| title_ar | string | Chapter title |
| first_hadith_no / last_hadith_no | integer | Range of hadith numbers |
| hadith_count | integer | Number of hadiths in the chapter |
Data version 8386dfc99199a5c9. The machine-readable spec is at /openapi.yaml (OpenAPI 3.1).