Developer documentation

Random Hadith API

Building an Islamic app, dashboard, home-screen widget, or learning tool? Fetch authentic hadith narrations as structured JSON — Arabic text, English translation, book metadata, and chapter information — without hosting your own database.

The API is read-only, returns application/json, and is designed for simple integration in any language that can make HTTP requests.

Quick start

The fastest way to display a random hadith is a single request to GET /api:

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

All responses are JSON. No API key is required. Requests must use HTTPS.

At a glance

Base URL

https://randomhadith.com

Combine the base URL with the endpoint path. Example: https://randomhadith.com/api/hadith?id=42

Supported collections

Responses draw from verified entries across major Sunni hadith compilations, including Sahih al-Bukhari, Sahih Muslim, Sunan Abi Dawud, Jami` at-Tirmidhi, Sunan an-Nasa'i, Sunan Ibn Majah. Each record includes the source book, chapter number, hadith number, and chapter titles in Arabic and English.

Browse the same content on the website via our hadith collections pages.

Endpoints

curl "https://randomhadith.com/api"

{
  "id": 12345,
  "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": "..."
}

curl "https://randomhadith.com/api/random"

{
  "id": 12345
}

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

{
  "id": 12345,
  "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": "..."
}

Response fields

Full hadith endpoints (/api and /api/hadith) return the same object shape:

Code examples

JavaScript (fetch)

const res = await fetch("https://randomhadith.com/api/hadith?id=12345");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const hadith = await res.json();

Python (requests)

import requests

response = requests.get("https://randomhadith.com/api", timeout=10)
response.raise_for_status()
hadith = response.json()
print(hadith["text_en"])

For production apps, call the API from your backend when possible so you can cache responses, respect rate limits, and handle errors consistently.

Rate limiting

Public API routes share one rate limit per client IP to keep the service available for all users. Plan your integration to avoid unnecessary repeat calls.

• 60 requests per 60 seconds per IP
• Both successful and failed requests count toward the limit
• Exceeding the limit returns 429 Too Many Requests
• Cache hadith responses locally when the same content may be shown again
• On 429, wait until the reset time in the response headers before retrying

Rate limit headers

Rate limit error response — 429

{
  "error": "Rate limit exceeded. Please try again later."
}

Error responses

Best practices

• Prefer GET /api when you only need one random hadith per user action.
• Store the returned id if users should return to the same narration later.
• Link to https://randomhadith.com/?id={id} so users can read the full page on Random Hadith.
• Credit Random Hadith when displaying text publicly — see our licensing page for attribution guidance.
• Contact us before high-traffic or commercial launches so we can discuss limits and licensing.