v3.0 — Now edge-cached worldwide

Authentic Hadiths,
one API call away.

A blazing-fast, completely free REST API serving hadiths in Bengali — with full-text search, grade filtering, pagination and global CDN caching. No API key. No rate limits. Just build.

⚡ Try the Playground Read the Docs
curl — quick start
$ curl https://hadith-api-three.vercel.app/api/random { "success": true, "data": { "id": 0, "narrator": "আবূ হুরায়রা (রাঃ) থেকে বর্ণিতঃ", "text": "যে ব্যাক্তি জ্ঞানার্জনের জন্য কোন পথে চলে, আল্লাহ্‌ তার জন্য জান্নাতের পথ সহজ করে দেন…", "reference": "মুসলিম ২৬৯৯", "grade": "সহিহ হাদিস", "gradeSlug": "sahih" } }
0
Hadiths served
0
Authenticity grades
0
Total visitors
∞
Free requests
Why this API

Built for speed. Designed for developers.

Every response is served from Vercel's global edge network with aggressive caching — typical response times are under 50ms.

⚡

Edge-cached & serverless

Responses are cached on Vercel's CDN across 100+ locations worldwide with stale-while-revalidate — practically instant, everywhere.

🔍

Full-text search

Search across narrator, hadith text, references and grade in a single query param. Pre-indexed at boot for O(n) scans over lowercase haystacks.

🏷️

Grade filtering

Filter by authenticity — sahih, hasan, daif, fabricated and more — using clean ASCII slugs alongside the original Bengali labels.

📄

Smart pagination

Consistent envelope with total counts, page metadata and hasNext / hasPrev flags. Up to 100 items per page.

🎲

Random endpoint

Perfect for “hadith of the day” widgets — grab 1 to 10 random hadiths, optionally restricted to a specific grade.

🌐

CORS enabled, no key

Call it straight from the browser, mobile apps or servers. No signup, no API key, no rate limits. 100% free forever.

Live Playground

Try it right now

Fire real requests against this deployment and inspect the JSON response — latency included.

GET
/api
Ready — press Send 
// The response will appear here…
API Reference

Five endpoints. Zero friction.

All endpoints return JSON with a consistent { success, data, meta? } envelope. Base URL is this site's origin.

GET /api/hadiths List, search & filter hadiths

Query parameters

ParamTypeDescription
qstringFull-text search across narrator, text, reference & grade
gradestringGrade slug: sahih · hasan · daif · fabricated · munkar · undetermined
pageintPage number (default 1)
limitintItems per page (default 20, max 100)

Example

curl "https://hadith-api-three.vercel.app/api/hadiths?grade=sahih&page=1&limit=10"
GET /api/hadiths/{id} Fetch a single hadith by id

Path parameters

ParamTypeDescription
idintHadith id (0-based). Returns 404 when not found.

Example

curl "https://hadith-api-three.vercel.app/api/hadiths/5"
GET /api/random Random hadith(s) — great for widgets

Query parameters

ParamTypeDescription
countintHow many random hadiths (default 1, max 10)
gradestringRestrict the random pool to a grade slug

Example

curl "https://hadith-api-three.vercel.app/api/random?count=3&grade=sahih"
GET /api/grades All grades with counts

Example

curl "https://hadith-api-three.vercel.app/api/grades"
GET /api API index & discovery

Example

curl "https://hadith-api-three.vercel.app/api"
GET /api/stats Site statistics — hadith count, visits, grades

Example

curl "https://hadith-api-three.vercel.app/api/stats"
ADMIN /api/hadiths — write access Add, edit & delete (admin key required)

Methods

MethodPathDescription
POST/api/hadithsCreate a hadith — body: narrator, text, reference, grade
PUT/api/hadiths/{id}Replace all fields of a hadith
PATCH/api/hadiths/{id}Update only the fields you send
DELETE/api/hadiths/{id}Remove a hadith

Authentication

curl -X POST "https://hadith-api-three.vercel.app/api/hadiths" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"narrator":"…","text":"…","reference":"…","grade":"sahih"}'

Or use the visual Admin Panel — no curl required.

Quick Start

Integrate in seconds

Copy-paste snippets for your stack of choice.

// Fetch a random sahih hadith
const res = await fetch('https://hadith-api-three.vercel.app/api/random?grade=sahih');
const { data } = await res.json();

console.log(data.narrator);  // আবূ হুরায়রা (রাঃ) থেকে বর্ণিতঃ
console.log(data.text);      // hadith text in Bengali
console.log(data.reference); // মুসলিম ২৬৯৯
import requests

res = requests.get(
    "https://hadith-api-three.vercel.app/api/hadiths",
    params={"q": "বিলাল", "limit": 5},
)
body = res.json()

for h in body["data"]:
    print(h["id"], h["reference"], h["grade"])
# List page 1, ten per page
curl "https://hadith-api-three.vercel.app/api/hadiths?page=1&limit=10"

# Search full-text
curl "https://hadith-api-three.vercel.app/api/hadiths?q=জান্নাত"

# Hadith of the day
curl "https://hadith-api-three.vercel.app/api/random"
function HadithOfTheDay() {
  const [hadith, setHadith] = React.useState(null);

  React.useEffect(() => {
    fetch('https://hadith-api-three.vercel.app/api/random')
      .then(r => r.json())
      .then(body => setHadith(body.data));
  }, []);

  if (!hadith) return 'Loading…';
  return (
    <blockquote>
      <p>{hadith.text}</p>
      <footer>{hadith.narrator} — {hadith.reference}</footer>
    </blockquote>
  );
}