---
title: "Developers — Random Hadith API"
description: "A clean, free, read-only JSON API for authentic hadith. No API key required."
last_updated: "2026-06-19"
---

# Developers — Random Hadith API

> A clean, free, read-only JSON API for authentic hadith. No API key required.

Every response is JSON and no API key is required. The base URL is `https://randomhadith.com`. Responses draw from Sahih al-Bukhari, Sahih Muslim, Sunan Abi Dawud, Jami` at-Tirmidhi, Sunan an-Nasa'i, Sunan Ibn Majah.

## Quick start

Fetch a complete random hadith with a single request:

```js
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.

### `GET /api/random`
Returns only a random hadith ID. Follow with `/api/hadith?id=` to load the full narration. Example response: `{ "id": 12345 }`.

### `GET /api/hadith?id={id}`
Returns a specific hadith by numeric ID (1–34,477) — for permalinks, bookmarks, and saved favorites. Example: `curl "https://randomhadith.com/api/hadith?id=12345"`.

## Response schema

A machine-readable OpenAPI 3.1 schema is available at [https://randomhadith.com/openapi.json](https://randomhadith.com/openapi.json).

| Field | Type | Description |
| --- | --- | --- |
| `id` | number | Unique identifier used across the site and API. |
| `book` | string | Name of the source collection. |
| `chapter_no` | number | Chapter number within the book. |
| `hadith_no` | string | Hadith number as referenced in the collection. |
| `chapter_name_en` | string | Chapter title in English. |
| `chapter_name_ar` | string | Chapter title in Arabic. |
| `text_ar` | string | Hadith text in Arabic. |
| `text_en` | string | Hadith text in English. |
| `text_ur` | string | Urdu text when available; may be empty. |

## Rate limits

The API is free for non-commercial use. Each client IP is allowed **60 requests per 60-second window** across all API routes. Both successful and failed requests count toward the limit; exceeding it returns `429 Too Many Requests`. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. No API keys are required for the public endpoints.

Building something commercial or high-volume? [Get in touch](https://randomhadith.com/pages/contact-us.md) for raised limits, and see the [licensing page](https://randomhadith.com/pages/licensing.md) for attribution terms.

## Sitemap

See the full [sitemap](https://randomhadith.com/sitemap.md) for all pages, or the machine-readable index at [https://randomhadith.com/llms.txt](https://randomhadith.com/llms.txt).