Random HadithAuthentic · Daily
REST API

Bring authentic hadith into your app

A clean, free, read-only JSON API. No keys required to fetch a random narration — start in a single request.

View endpoints

Quick start

Every response is JSON and no API key is required. The base URL is:

base url
https://randomhadith.com

Fetch a complete random hadith with a single request:

javascript
fetch("https://randomhadith.com/api")
  .then((res) => res.json())
  .then((hadith) => {
    console.log(hadith.text_en);
    console.log(hadith.book, hadith.chapter_name_en);
  });

Endpoints

GET/api

Returns a complete, randomly selected hadith — ideal for daily-hadith widgets and one-call integrations.

200 OK · application/json
{
  "id": 1,
  "book": "Sahih al-Bukhari",
  "chapter_no": 1,
  "hadith_no": "1",
  "chapter_name_en": "How the Divine Revelation started",
  "chapter_name_ar": "باب كيف كان بدء الوحي",
  "text_ar": "...",
  "text_en": "...",
  "text_ur": "..."
}
GET/api/random

Returns only a random hadith ID. Follow with /api/hadith?id= to load the full narration.

200 OK · application/json
{ "id": 12345 }
GET/api/hadith?id={id}

Returns a specific hadith by numeric ID (1–34,477) — for permalinks, bookmarks, and saved favorites.

curl
curl "https://randomhadith.com/api/hadith?id=12345"

Responses draw from Sahih al-Bukhari, Sahih Muslim, Sunan Abi Dawud, Jami` at-Tirmidhi, Sunan an-Nasa'i, Sunan Ibn Majah.

Response schema

A machine-readable OpenAPI 3.1 schema is available at /openapi.json.

idnumberUnique identifier used across the site and API.
bookstringName of the source collection.
chapter_nonumberChapter number within the book.
hadith_nostringHadith number as referenced in the collection.
chapter_name_enstringChapter title in English.
chapter_name_arstringChapter title in Arabic.
text_arstringHadith text in Arabic.
text_enstringHadith text in English.
text_urstringUrdu text when available; may be empty.

Rate limits

The API is free for non-commercial use. Limits are applied per client IP to keep it fast for everyone. Both successful and failed requests count toward the limit; exceeding it returns 429 Too Many Requests.

60
Requests / 60s
3
Public endpoints
0
API keys required

Building something commercial or high-volume? Get in touch for raised limits, and see our licensing page for attribution terms.

Developer FAQ

See the questions below for keys, caching, attribution, and limits.

Questions

Developer FAQ

Common questions about integrating the Random Hadith API, rate limits, licensing, and production use.

Is the Random Hadith API free to use?
Yes. The API is free for personal projects, prototypes, and non-commercial educational use. You can call the endpoints without signing up or paying a fee. If you plan to use the API in a commercial product, at high volume, or in a way that requires a separate license, review our licensing terms and contact us before launch.
Do I need an API key or authentication?
No API key is required. All public endpoints accept unauthenticated GET requests over HTTPS. Rate limits are applied per IP address to keep the service fair and stable for everyone.
What is the difference between /api and /api/random?
GET /api returns a complete random hadith in one response — Arabic text, English translation, book name, chapter details, and metadata. GET /api/random returns only a random numeric ID. Use /api when you want the full narration immediately. Use /api/random when you only need an ID and will fetch the full record separately via GET /api/hadith?id=....
Which hadith collections does the API include?
The API serves narrations from major Sunni collections including Sahih al-Bukhari, Sahih Muslim, Sunan Abi Dawud, Jami' at-Tirmidhi, Sunan an-Nasa'i, and Sunan Ibn Majah. Each response includes the source book, chapter number, chapter titles in Arabic and English, and the hadith reference number.
What are the rate limits?
Each client IP is allowed 60 requests per 60-second window across all API routes. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can track usage. If you exceed the limit, the API returns HTTP 429 with a JSON error message. Cache responses where possible and implement backoff before retrying.
Can I use the API in a commercial mobile app or SaaS product?
Non-commercial and educational integrations are welcome under our standard terms. Commercial use — including paid apps, subscription services, or products that monetize hadith content — may require a separate commercial license. See the licensing page for details and contact us with your use case if you need written permission or higher limits.
Can I call the API directly from a browser (client-side JavaScript)?
Server-side requests from your backend, scripts, or mobile apps are the most reliable approach. Browser-based calls from another website may be blocked by cross-origin restrictions depending on your setup. For production apps, proxy API calls through your own server so you can cache results, handle errors gracefully, and stay within rate limits.
How should I attribute hadith content from the API?
When displaying hadith text publicly, credit Random Hadith and link back to randomhadith.com where practical. Our licensing page includes recommended attribution wording and explains permitted use under CC BY-NC 4.0 for hadith content. Do not remove source references or present our translations as your own original work.
What valid ID range can I use with /api/hadith?
Hadith IDs are numeric values from 1 to 34,477. Requests with a missing, non-numeric, or out-of-range ID return a 400 error. If the ID is valid but no record exists, the API returns 404 with an error object that includes the requested ID.
How do I request higher rate limits or bulk access?
If your project needs sustained traffic beyond the public limits, contact us through the contact page with a brief description of your application, expected request volume, and timeline. We review requests individually and can discuss custom arrangements for approved commercial or high-traffic use.