Jawami' al-Kalim API

Quick start

The base URL is https://hadith.adhamzahran.com/api. Every example below has a Try button that runs it.

A narrator (Ibn Abbas), with a link to him on the website:

The first five sahih narrations of Sahih al-Bukhari (book 146), only two columns:

Search, the same search as the website:

curl -G "https://hadith.adhamzahran.com/api/search" \
  --data-urlencode 'q=إنما الأعمال بالنيات' --data-urlencode book=146

Conventions

• Read-only, except for reports. GET, HEAD and OPTIONS everywhere, plus POST /api/reports to report a mistake; anything else is a 405.
• JSON in UTF-8. Arabic comes back as Arabic, not \u0627 escapes.
• Open CORS (Access-Control-Allow-Origin: *), so a web page can call it directly.
• Cacheable. The data never changes, so responses carry Cache-Control: public, max-age=3600. Reports do change, so /api/reports is never cached.
• No key and no rate limit for now. Please be gentle, and use the full download if you want everything.
• Ids are not coerced. Some id columns are text and some are numbers (for example books.book_id and clusters.cluster_id come back as strings, narrators.id as a number). Filtering works either way; compare by value.
• bhid identifies one narration: <book_id>_<number>, e.g. 146_1 is the first narration of Sahih al-Bukhari.

Routes

Filtering, columns and order

Any column of a table can be a filter: column=value means equals, and column=op.value uses an operator. Several filters must all match.

• Ranges: repeat the column: hadith_num=gte.10&hadith_num=lt.13.
• Comparing ids: gt/lt on a text id (book_id, bhid, cluster_id) compares as text, so "9" > "10". Number columns like hadith_num compare as numbers.
• A literal value that looks like an operator: prefix it with eq., e.g. name=eq.like.x.
• fields=a,b returns only those columns.
• order=col sorts ascending, order=col.desc,other sorts by several. Without it rows come in stable table order.
• Filtering on any short column is fast: they are all indexed (the reference marks which). A like.*word* inside a long text column has no index and reads the table, which takes a few seconds on commentaries and dictionary.

Paging and totals

A list returns:

{
  "data": [ { "book_id": "146", "name": "صحيح البخاري" }, ... ],
  "limit": 2,
  "offset": 0,
  "next": "/api/books?fields=book_id%2Cname&limit=2&count=1&after=1402",
  "total": 1400
}

• limit defaults to 20 and is capped at 100.
• Follow next until it is null. It is a ready-made URL, so you never build paging yourself. In the default order it pages by key (fast however deep you go); with a custom order it pages by offset, which gets slower the deeper you go.
• count=1 adds total. It is opt-in because counting a big table is slow.

A single row (/api/narrators/4883?fields=id,name,rotba,wasf_rotba) is returned bare, not wrapped in data:

{
  "id": 4883,
  "name": "عبد الله بن عباس بن عبد المطلب بن هاشم بن عبد مناف",
  "rotba": 1,
  "wasf_rotba": "صحابي",
  "ui_url": "https://hadith.adhamzahran.com/#view=narrator&id=4883"
}

Search

There are three ways to search, from the most convenient to the most flexible.

1. /api/search: the website's search

• One word is expanded to every form of its root: searching الأعمال also finds عماله, أعمالنا and استعملنا. The response says so in root_used, morphological and form_count.
• Several words are searched as an exact phrase first; if nothing matches, as all the words anywhere in the narration.
• Each result has a snippet with the matches wrapped in <mark>, its grading, and a ui_url to the narration on the website.

{
  "total": 26527, "page": 1, "pages": 26527,
  "results": [ {
    "bhid": "2028_6", "book_id": "2028", "hadith_num": 6,
    "book_name": "...", "author": "...",
    "snippet": "...إلى <mark>عماله</mark> : إياكم أن <mark>تستعملوا</mark> على...",
    "cluster_id": null, "hokm": null, "hokm_label": "غير محدد",
    "ui_url": "https://hadith.adhamzahran.com/#view=hadith&bhid=2028_6"
  } ],
  "root_used": "عمل", "morphological": true, "form_count": 400,
  "ui_url": "https://hadith.adhamzahran.com/#view=search&q=..."
}

It runs the same code as the website's search box, so the results match what you see there. The top-level ui_url opens the same search on the website.

2. /api/hadith_fts?q=: raw full-text syntax

For when you want control: "exact phrase", a OR b, word*, a NOT b. Rows come ranked by relevance with a snippet, and can be combined with the usual filters and fields. A malformed query is a 400. There is no root expansion here.

3. Filters on any table

Everything else (narrator names, critics' wording, commentary text, dictionary entries) is searched with like: /api/critic_opinions?opinion=like.*اختلط*. A prefix match (name=like.عبد*) is instant on an indexed column; a match in the middle of long text reads the table.

Links to the website

Every hadith and every narrator comes with a link to its page on the website, so a result is one click from the full view (the isnad tree, the takhreej, the biography). The links are added to the rows by the API, whichever table they come from, and even when fields= left the key column out.

Recipes

Common questions and the requests that answer them.

Find a narrator, then everything about him

The second one is what every critic said about him; alem_id is the critic, see /api/critics/{alem_id}.

Every isnad a narrator appears in

The isnads store their narrators as a comma-separated list (sanad.rawy_ids), which cannot be searched efficiently. So the same data is also split into a table with one row per narrator in a chain:

Each row says which isnad (sanad_id) and where in it he stands (pos, counted from 0: 0 is the compiler's side, the last position is the companion). Fetch the isnad itself with /api/sanad/{sanad_id}, which carries its bhid, grading and every narrator's link. The same pattern covers companions: /api/hadith_sahabi?rawy_id=4883 lists the narrations he is the companion of, and book_cluster_sahabi does the same for book_clusters.

The isnads of one narration, and its text

The same hadith in every book

Narrations of the same hadith share a cluster_id:

Commentary on a narration

commentary_book says which: 1 Fath al-Bari, 2 Sharh al-Nawawi, 3 Awn al-Ma'bud, 4 Tuhfat al-Ahwadhi.

A word's root

Reports

If you find a mistake in the data, or a bug in the website or this API, report it here. This is the only route that takes a POST. Reports are public (anyone can read them below), so don't put personal information in one. They are kept in a file of their own, so they are not part of the database download.

Send a report

curl -X POST https://hadith.adhamzahran.com/api/reports \
  -H 'Content-Type: application/json' \
  -d '{"kind": "data",
       "problem": "missing",
       "table": "sanad",
       "bhid": "146_4412",
       "narrator_id": 3954,
       "message": "No sanad row. The text names 1548, 896, 1302, 3954, 4049.",
       "suggested": "1548,896,1302,3954,4049",
       "source": "islamic-debate.adhamzahran.com"}'

Only kind and message are required.

• The body is a JSON object, or a form (application/x-www-form-urlencoded, which is what curl -d sends). Any other field is a 400, including status: only the maintainer sets that.
• For a problem with the website, say where in message: the page, what you did, and what you saw.
• The answer is 201 Created, with a Location header and the stored report:

{
  "id": 7,
  "created_at": "2026-10-25T14:11:59Z",
  "kind": "data",
  "status": "open",
  "table": "sanad",
  "key": null,
  "column": null,
  "message": "No sanad row. The text names 1548, 896, 1302, 3954, 4049.",
  "problem": "missing",
  "bhid": "146_4412",
  "narrator_id": 3954,
  "suggested": "1548,896,1302,3954,4049",
  "source": "islamic-debate.adhamzahran.com",
  "bhid_ui_url": "https://hadith.adhamzahran.com/#view=hadith&bhid=146_4412",
  "narrator_id_ui_url": "https://hadith.adhamzahran.com/#view=narrator&id=3954"
}

Read the reports

Reports behave like any table: the same filters, fields, order, paging and count, and /api/reports/{id} for one. They come newest first unless you set order. The columns are the ones in the response above, so any of them filters: everything reported about a narration (bhid=), a narrator (narrator_id=) or a table, everything of one problem, everything from one source. status starts as open and becomes fixed or rejected (the Codes list the values of kind, problem and status). Links to the website come as for any table: bhid_ui_url and narrator_id_ui_url, and ui_url when table and key name a narration or a narrator.

The same list is a page on the website: /#view=reports.

Errors

Errors are JSON with the reason, never HTML: {"error": "unknown column: bogus"}.

Tables

Every table in the database, read live from /api/. indexed columns filter and sort fast. Click a table for its columns.

Codes

Columns whose values stand for something, read live from /api/.

Bulk download

If you want all of it, don't page through the API: download the whole database as one SQLite file from Hugging Face (under 600 MB compressed). The API is read-only on that same file, so every column and table listed here is in it, and the table descriptions are on that page. Reports are the exception: they are not part of the database.