الحديث النبوي الشريف

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.

50,759hadiths
17collections
606chapters
Public domainArabic text
Base URLhttps://hadeeth.rayan-app.com

Quick 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/1
const 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
Never put a key in the URL. Requests with ?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

AccessPer minutePer day
No key (per IP)301,000
Free key12020,000
Pro key600250,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-LimitPer-minute budget
RateLimit-RemainingUnits left in the current bucket
RateLimit-ResetSeconds until the bucket is full again
X-RateLimit-Daily-LimitDaily budget
X-RateLimit-Daily-RemainingUnits left today
Retry-AfterOnly 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" } }
StatusCodesMeaning
400bad_param bad_number bad_query key_in_queryThe request is malformed
401invalid_keyThe API key is unknown or revoked
404not_found unknown_bookNo such hadith, collection or endpoint
429rate_limitedSlow down; see Retry-After
5xxinternal timeoutOur 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

GET/v1/books

Lists all collections with their hadith counts.

GET/v1/books/{slug}

Returns one collection. slug is one of the values in the collections table.

GET/v1/books/{slug}/chapters

Lists a collection's chapters (كتب / أبواب) in order, with the range of hadith numbers in each.

GET/v1/books/{slug}/hadiths

Pages through a collection in hadith-number order.

ParamDescription
limit1–100, default 20
cursorThe meta.next_cursor value from the previous page
GET/v1/books/{slug}/hadiths/{no}

Returns one hadith by its number in the collection.

GET/v1/random

Returns a random hadith, chosen uniformly from all collections or from one with ?book=. Responses are not cached.

GET/v1/stats

Returns dataset totals, hadith counts per collection, and the data_version hash.

Collections

SlugCollectionCompilerHadiths
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

bookstringCollection slug
hadith_nointegerNumber within the collection
chapter.indexinteger1-based chapter position in the collection
chapter.title_arstringChapter title
arabicstringFull Arabic text (isnād + matn) with diacritics
scorenumberSearch results only; higher is more relevant

Book

idintegerStable numeric id
slugstringUsed in URLs
name_arstringCollection title
author_arstringCompiler
hadith_countintegerNumber of hadiths

Chapter

indexinteger1-based position
title_arstringChapter title
first_hadith_no / last_hadith_nointegerRange of hadith numbers
hadith_countintegerNumber of hadiths in the chapter

Data version 8386dfc99199a5c9. The machine-readable spec is at /openapi.yaml (OpenAPI 3.1).