TL;DR Check out the swagger documentation and test it. It's completely free.
Free and Open Source Multilingual (arabic (+diacritics), english, bengali, indonesian, french, turkish, tamil, russian) REST API for most popular hadith editions including :
- Forty Hadith of Shah Waliullah Dehlawi
- Muwatta Malik
- Sahih al Bukhari
- Sahih Muslim
- Sunan Abu Dawud
- Sunan an Nasai
- Jami At Tirmidhi
- Forty Hadith of an-Nawawi
- Sunan Ibn Majah
- Forty Hadith Qudsi
Not all editions support all of those languages but english and arabic are present for all.
The API is available here : hadislam.org/
Quick summary
Open-source REST API developed with FastAPI for structured access to:
- The most popular editions
- Related books (i.e a big chapter of an edition)
- Language-aware hadith
- Grade for hadith
Why “Hadislam”?
The name Hadislam combines Hadith and Islam, reflecting the project’s purpose: to provide easy, open-source access to authentic Hadith resources. It’s designed for developers and enthusiasts who want a reliable API to explore most popular Islamic Hadith sources.
- FastAPI-based REST API
- OpenAPI docs (
/docs) and ReDoc (/redoc) - Pagination support for list endpoints
- Optional language filtering
GET /— API metadata and docs links
GET /editions/— List all editionsGET /editions/{slug}— Get one edition by its hyphen separated latinized english name (i.e slug)
GET /books/— List booksGET /books/{book_id}— Get one book by his unique idGET /editions/{slug}/books— List edition's booksGET /editions/{slug}/books/{book_index}— Get an edition's book at positionbook_index
/hadiths— List hadiths/hadiths/{hadith_id}— Get one book by his unique id/editions/{slug}/hadiths— List edition's hadiths/editions/{slug}/hadiths/{hadith_index}.{hadith_index_minor}— Get one minor (that is a sub hadith of a hadith) hadith by his numerical position inside the edition/editions/{slug}/hadiths/{hadith_index}— Get one hadith (including his sub-hadith) by his numerical position inside the edition/editions/{slug}/books/{book_index}/hadiths— List hadiths of an edition's book/editions/{slug}/books/{book_index}/hadiths/{book_hadith_index}— Get one hadith (including his sub-hadith) by his relative numerical position inside the book
/hadiths/search?q=...— Performs a full-text search on hadiths based on queryq. English by default.
- Python
>=3.12 uvpackage managerpre-commit
uv syncuv run fastapi run src/main.py --reloaduv run pytest tests -v --durations=0 --cov --cov-report=term-missingType
uv run ty check .
Format
uv run ruff check .
uv run ruff format .
- Define improvement guidelines for contributors
- Improve API docs with request/response examples
- Create issue templates for consistent reporting
- Create a AGENTS.md file
- Create a better rate limit policy
- Integrate Redis for faster data retrieval
- Add unit tests for core functionality
- Add Docker for quick local development
- Insert bulk data into local environment for quick start
- Add Bruno (team or collaborator)
This project is licensed under the MIT License. See LICENSE.
Have suggestions, feedback, or need support? Open an issue or start a discussion — we’d love to hear from you.
We welcome all kinds of contributions! Here's how you can help :
✅ Improve the Dataset
to be written
If you want to support me financially you can buy me a coffee it will certainly motivate me on continously improving the REST API. May Allah rewards you !
You can read my ko-fi post and add a comment.
📬 A quick thank-you
If this project helped you, you can send me a message.
You don’t have to donate — even a simple message of support or a quick “thank you” means a lot and keeps me motivated to continue improving this project.
Your encouragement truly makes a difference 🙌
