hadith-api and a hadith corpus served as static JSON on a CDN

The service is a repository, not a server

Hadith API is described as a free hadith API service with multiple languages and multiple grades, and the listed features are free and blazing fast response, no rate limits, multiple languages and multiple grades.

What makes that possible is the delivery mechanism, and the README is explicit about it. The URL structure is a jsDelivr path into a GitHub repository, with the API version as a tag:

`https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@{apiVersion}/{endpoint}`

So there is no application server, no database query layer and no authentication. The data is JSON committed to the repository, and jsDelivr serves it. The default branch of the repository is 1, and the example URLs in the README all use the @1 tag, so the version in the path is what pins the data to a particular state of the repository.

The consequence for a reader evaluating this is that the request path is the API. There is no /hadiths?book=abudawud&number=1035 query string, because there is nothing to query. What you get is a set of files whose names encode the selection you want, and the selection is expressed by the path.

The project is licensed under the Unlicense, and the repository has no GitHub releases, so the version of the data is whatever the referenced branch or tag contains. The last push to the repository was on 2026-06-03, and the repository is not archived.

The audience is a developer building something that displays hadith: an app, a website, a chat bot, a search tool. The demos the README lists, including a Quran and hadith search engine, a Hadiths site and a SQLite data build, are all front ends over this data rather than separate services.

The endpoint grammar, from edition list to single hadith

The endpoints are four, and they nest. That nesting is the entire interface, so it is worth walking through it exactly as the README documents it.

The first is /editions, which lists all the available editions in prettified JSON. The second is /editions/{editionName}, which gets the whole hadith or hadith translation for that edition. The third is /editions/{editionName}/{HadithNo}, which gets one hadith, with the example given as the 1035th hadith. The fourth is /editions/{editionName}/sections/{sectionNo}, which gets a section, with the example being section 7.

The edition name is a slug that combines language and collection, and eng-abudawud is the one used throughout the examples, English with the Abu Dawud collection. The list of what is actually available is the editions endpoint itself, which is the discovery mechanism: you fetch editions.json, read the slugs, and then request the ones you need.

Two file sizes are published for everything. The pretty version is the endpoint with .json, and the minified version is the endpoint with .min.json, and the README notes that both formats work as a fallback for each other, so if the .min.json link fails you can use the .json link and vice versa.

That fallback is not optional in practice. The README carries a warning that you should include a fallback mechanism in your code, and links to an issue about avoiding problems. The reason is structural: the minified files are large and the pretty ones are large too, and a client that hardcodes one format and treats a failure as fatal will break when a CDN cache expires mid-request or a link is briefly unavailable.

There is also an /info endpoint, which returns all the details about the hadith book, such as hadith grades and book references. That is the endpoint to read before you build anything, because the grades in particular are the part of this corpus that a naive integration will get wrong.

Two formats, one URL shape, and how to write the client

The endpoints support the HTTP GET method and return data in two formats, .json and .min.json, with the fallback rule between them. Nothing else is documented about the transport: there is no mention of CORS headers, custom headers, API keys or query parameters, and there is no client SDK in the package metadata.

Which means the client is a fetch. The pattern is short enough to be worth writing out as a skeleton, and the shape of the four URLs is what you would request:

https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions.json
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud.json
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud/1035.json
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud/sections/7.json

The first call is the one you make at startup, or at build time, to learn which editions exist. The second is the expensive one, because a whole book in a language can be a large file, and the last two are the ones you would call for a single item or a chapter, which are much smaller.

A sensible client therefore does not fetch a whole edition to display one hadith. It fetches the edition list, resolves the slug, and then requests the specific hadith or section it needs. Whether you do that at runtime or bake the data into your build is your choice, and the demos in the README show both patterns, including a SQLite build of the corpus for local search.

The other thing your client has to own is caching. Since the data is immutable for a given tag, a client that caches a whole edition in memory or in a local database pays the download cost once. The README does not describe any cache headers or ETag support, so a sensible client should treat the URL as cacheable by tag rather than relying on the CDN to tell it when to revalidate.

What is in the repository, and how the data is built

The repository is more than the published JSON. Alongside the README there is an editions/ directory with the per-edition files, a database/ directory, an others/ directory, a start/ directory, and a set of scripts with revealing names: apiscript.js as the package main entry, utilities.js, infofixer.js, a command.txt, a log.txt, and package.json and package-lock.json.

The dependencies of those scripts are the key to understanding the pipeline. The package declares node-fetch at ^3.2.3 and playwright at ^1.49.1, and playwright is a browser automation library. That combination says the edition data is not hand-written; it is extracted by driving a headless browser against source documents and normalising what comes back. The database/ directory and the Preprocessing.md and dev.md files in the root describe that preparation, and download.md covers getting the data locally.

There is an inconsistency in the metadata worth flagging, because it affects anyone vendoring the code. The repository licence is listed as the Unlicense, which places the work in the public domain, while the package.json declares the licence as ISC. For the published JSON data that discrepancy matters little, since the Unlicense is the more permissive of the two, but for the scripts in the repository it is the kind of thing worth resolving before you copy code out of it.

The package.json also shows the version at 1.0.10, and the test script is a placeholder that prints an error and exits, meaning there is no automated test suite for the scripts. The testing story here is manual, against the published endpoints.

The repository also carries a References.md file listing the open source projects and dawah and Islamic organizations the data came from, and the contribution guidance asks for new translations to be shared or added directly, with a CONTRIBUTING file explaining how. Adding a language is therefore an open contribution path, and the README is direct that without contributions the work will not survive.

Limitations that follow from the design

Three constraints are worth being explicit about.

The first is that there is no query capability. Every endpoint is a file path. If you want the hadiths matching a topic, or all hadiths by a narrator, or a search across the corpus, you have to fetch the edition and filter client-side, or build your own index as the SQLite demo does. For a small book that is fine. For a large corpus across many editions, it means either a lot of downloading or a preprocessing step, and both are your problem rather than the service's.

The second is that the service is only as available as a public CDN. There is no uptime commitment, no status page, no contract, and the data lives in a GitHub branch. The README frames this as a feature, and it is: no rate limits means no throttling to handle and no key to leak. But it also means an outage of jsDelivr or a bad deploy to the branch takes the corpus down for everyone at once, and there is no fallback other than the .json and .min.json variants of the same file.

The third is versioning. The apiVersion in the URL is the tag or branch, and the default branch of the repository is 1, so the example URLs are pinned to a major version. The data inside that version can still change, since a translation fix or a new hadith correction would be a commit to the branch, not a new release, and the repository has no GitHub releases at all. If you need a byte-stable snapshot, you have to pin to a commit rather than the branch, and the README does not describe that workflow.

There is also a correctness question that the project itself flags. The /info endpoint exists because hadith data carries grades, and grades differ between collections and between scholars. A client that displays a hadith without its grade, or with a grade from the wrong edition, will misrepresent the source, and the /info endpoint is where the mapping lives.

How this differs from running your own hadith database

The obvious alternative is to not use this at all and host the corpus yourself, which is what a few of the linked community projects do.

The difference in approach is that hadith-api gives you a set of static files on a shared CDN with a URL grammar, while a self-hosted setup gives you a database you control, with a schema you design, an index you build, and full-text search over whatever fields you decide to index.

What you gain by self-hosting is control. You can index across editions, you can answer arbitrary queries, you can serve your own users without a dependency on jsDelivr, and you can pin an exact snapshot. The cost is that you inherit the whole pipeline. The scripts in this repository use a headless browser to extract the data, and if you are going to maintain that extraction against upstream sources, you are taking on the maintenance burden the project was created to avoid.

The middle option, which the demos illustrate, is to use the static files as the source and build your own derived artefact. The Hadiths SQLite Data project is exactly that shape: take the published JSON, convert it into a local SQLite file, and serve your own queries from it. That gives you the availability and licensing simplicity of the static files with the query power of a local database, at the cost of a build step and storage.

For a small project that only needs to show a hadith and its translation, using the CDN directly is the shortest path by a wide margin, and the absence of rate limits is what makes it viable for a popular app. The trade becomes real when your needs cross into search, at which point the derived-index approach keeps the data source and drops the query limitation.

Editorial conclusion

hadith-api is a good fit for a frontend, bot or app that needs to display hadith text and translations without running a server or negotiating a rate limit, because the whole corpus is static JSON behind one URL pattern and the same pattern gives you list, book, hadith and section granularity. It is a poor fit if you need a query API with filtering, because the endpoints are file paths rather than queries, and a poor fit if you need a service-level commitment, since the data is served by a public CDN from a repository branch. Before adopting, read the /info endpoint for the grades and book references, and implement the fallback between the .json and .min.json URLs that the README warns about, because the minified links are the ones that can fail silently in a cached client.

Frequently asked questions

Official sources

1. fawazahmed0/hadith-api on GitHub
2. Issues
3. License: Unlicense
4. README