Classical Islamic library (Shamela, 8,594 books): verbatim Arabic cited by volume and page. No key.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional. Free Quran Gallery API key as a bearer token: 60 tool calls a minute with no daily cap, instead of the keyless 10 a minute and 200 a day. Create one at https://accounts.qurangallery.com/developers. Omit the header to use the server with no account.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Read one library page whole by the id `search` returned: main text, then its footnotes under their own label (the editor's words, never the author's), with book, author, printed volume/page, edition data and the shamela.ws link. Use shamela_read instead to read one body part at a time (unit "page"), a run of pages (unit "range") or a whole chapter (unit "section"), and shamela_cite (mode "printed_page") to turn a printed volume and page into ids. Not a search. Long pages are cut at 4 body parts of about 4,000 characters (2 without an API key): metadata.complete false, ending with the shamela_read call that continues it. A malformed id, or a page the library does not hold, returns a tool error.
Page id "{bookId}:{pageId}", e.g. "1681:10" — Shamela internal ids from a `search` result, not printed page numbers. Malformed or unknown ids return a tool error.
Read one library page whole by the id `search` returned: main text, then its footnotes under their own label (the editor's words, never the author's), with book, author, printed volume/page, edition data and the shamela.ws link. Use shamela_read instead to read one body part at a time (unit "page"), a run of pages (unit "range") or a whole chapter (unit "section"), and shamela_cite (mode "printed_page") to turn a printed volume and page into ids. Not a search. Long pages are cut at 4 body parts of about 4,000 characters (2 without an API key): metadata.complete false, ending with the shamela_read call that continues it. A malformed id, or a page the library does not hold, returns a tool error.
| Argument | Type | Description |
|---|---|---|
| id* | string | Page id "{bookId}:{pageId}", e.g. "1681:10" — Shamela internal ids from a `search` result, not printed page numbers. Malformed or unknown ids return a tool error. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Page id \"{bookId}:{pageId}\", e.g. \"1681:10\" — Shamela internal ids from a `search` result, not printed page numbers. Malformed or unknown ids return a tool error."
}
},
"additionalProperties": false
}Search the whole classical Islamic library (8,594 works, no scope) and get up to 10 pages as {id, title, url}; pass an id to `fetch` to read the page. This is the generic one-argument entry (the standard search/fetch pair); the scoped tools answer research questions better. Use shamela_search_library for a hadith, tafsir or fiqh question: unscoped ranking is by term frequency, so a poetry anthology can outrank Sahih al-Bukhari. Use shamela_search (match "words", "phrase", "near", "exact" or "boolean") to pin books, categories or a madhhab, match an exact or diacritized phrase, or page further; use shamela_cite (mode "printed_page") for printed-page citations. Exact phrase first; only when it finds nothing are the words matched separately. Title flags: [footnote match] = only an editor's footnote; [token match] = words occur apart; [near match] = only some words or their roots. Empty results mean no page carries the words. A query without Arabic words returns a tool error.
| Argument | Type | Description |
|---|---|---|
| query* | string | Arabic search text, e.g. "إنما الأعمال بالنيات"; 2-6 words work best. Quote the wording if known, else name the topic. |
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Arabic search text, e.g. \"إنما الأعمال بالنيات\"; 2-6 words work best. Quote the wording if known, else name the topic."
}
},
"additionalProperties": false
}Citations. mode=citation (default): build one for a book, optionally a page and quoted text — Shamela's copy format, short inline, full with death year, or BibTeX/RIS. Call it whenever you attribute a quote; it needs only the catalogue, plus the installed text for a page's printed number. Read page_resolved, components.auto_numbered and notes[] before presenting. mode=printed_page: map a printed citation («vol. 4, p. 405») to the page_ids carrying it — no arithmetic relates the two, and one printed page often spans several ids: read them all, in order, with shamela_read(unit='page'). Resolve the work with shamela_find(kind='work') first; holding a page_id already, skip this. Failures come back as `status`; citable:false = Shamela's own numbering. Error: BOOK_NOT_FOUND.
| Argument | Type | Description |
|---|---|---|
| mode | string | Selects what the call does: citation | printed_page. Default citation. |
| page | integer | The PRINTED page number as the citation gives it (e.g. 405). Example: {book_id:6910, part:'4', page:405}; {book_id:1681, part:'1', page:6}. (mode=printed_page only.) |
| part | string | The volume/part label as the book uses it, usually a bare number ('4'). Omit when the citation names no volume or the work is single-volume: the search then runs across every part and the response reports which parts matched, so an ambiguous page number is visible rather than silently resolved to the first volume. (mode=printed_page only.) |
| text | string | Optional quoted text. Used by the 'shamela' style only, which then prints a two-line block: «<book>» (<part>/ <page>): «<text>». Other styles ignore it. (mode=citation only.) |
Catalogue lookup — which books, headings, authors and shelves exist, not page text. `kind`: - book (default): titles, authors, publication lines, subject descriptions → book_ids, installed or not. no_title_match: not proof the book is held. downloaded:false → another edition (shamela_get_details(kind='book') same_group) or catalogue metadata only. - heading: chapter/section headings, i.e. where books treat a topic; open with shamela_read(unit='section', book_id, title_id). No hits = no heading carries the words: drop words or use shamela_search(match='words'). - author: names and biographies → author_id, Hijri death year, book count; no scope. Empty is not absence: retry kunya, nisba or shuhra (ابن قدامة / الموفق / المقدسي). - category: the 41 flat shelves with catalogue and installed counts → scope.category_ids. A subject spans ids (Qur'anic studies 3 tafsir, 4 Qur'anic sciences/usul al-tafsir, 5 tajwid/qira'at; fiqh 14–17 by madhab): pass all that apply. downloaded_only:true when choosing shelves to search or read. - work: verify a cited title (optional author, edition); refuses rather than guesses; catalogue only, text need not be installed. - name: fuzzy best guess over book/author names, for an id; always answers, so never use it to verify a citation. - period: books by Hijri window, bounds ANDed (scope.period_* on searches unions them). Rules: a parameter of another kind is refused; book/heading/author/period page with limit/offset until has_more is false. Instead: page text → shamela_search; a printed page → shamela_cite(mode='printed_page'); one book's headings → shamela_read(unit='toc').
| Argument | Type | Description |
|---|---|---|
| kind | string | Selects what the call does: book | heading | author | category | work | name | period. Default book. |
| type | string | 'book' matches catalogue titles only, 'author' author names only, 'any' (default) both, returned as separate books[] and authors[] lists. Reads the s_book/ and s_author/ n-gram indexes (fast partial matching). Example: {query:'ابن قدامة', type:'author'}. (kind=name only.) |
Return this server's machine-readable capability handshake: capabilities, numeric limits, retired tool names with their replacements, and traps (ways a result misleads, each with the response field that proves it fired). Call it first from a programmatic client: inputs are strict, so an argument an older build lacks (e.g. `shape`, response_format:'none') is a hard validation error that fails the whole call, and tools/list cannot reveal argument support — gate each new argument on its capability string. Cache by brief_hash and re-fetch only when it changes. Constants only: needs no library access and does not fail. Example: {} or {response_format:'json'}.
| Argument | Type | Description |
|---|---|---|
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"default": "markdown",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}Catalogue record for one book (kind=book, default) or one author (kind=author), installed or not. - book: authors, category, type, printed-edition flag, whether the text is installed here, the scanned printing and the other editions of the same work (same_group). When a reader tool says BOOK_NOT_DOWNLOADED, pick an installed entry from same_group or answer from this record. Read book_date, edition, editor and publisher per their field notes: never supply a missing one. - author: name, Hijri death year (null = unknown or living) and every catalogued book they wrote or co-wrote, each flagged installed or not. Volumes → shamela_read(unit='parts'); a book by title or subject → shamela_find(kind='book'). Errors: BOOK_NOT_FOUND, AUTHOR_NOT_FOUND.
| Argument | Type | Description |
|---|---|---|
| kind | string | Selects what the call does: book | author. Default book. |
| book_id | integer | The book id (e.g. 9942). (kind=book only.) |
| author_id | integer | The author id (e.g. 474 for Ibn Qudama, 57 for Ibn Uthaymeen), from shamela_find(kind='name') with type 'author' or a book's authors[]. A catalogue id, not a death year or book id; shamela_find(kind='author') also gives it. (kind=author only.) |
| include_books | boolean | If true (default), include every catalogued book by this author, main or co-author, ordered by book_id. False returns name and death year only. (kind=author only.) |
| include_cover | boolean | Attach the book's cover image as an MCP image block when Shamela ships one (1,368 of 8,594 books). The picture is a ~310x460 thumbnail of the scanned printing's title page, so it costs roughly 190 image tokens. Set false to keep the reply text-only; `cover.available` still reports whether one exists. Default: true. (kind=book only.) |
Hadith. mode=search (default): find a hadith by its wording and trace its takhrij — searches the hadith shelves (Sunnah collections, commentaries, takhrij, hadith sciences) in matn and footnotes, reads hadith keys off the matching pages and lists every collection indexing the same hadith. No offset; if the full text matches nothing, one word is dropped and named in `relaxed`. Takhrij covers only key_index_books, so few rows is not proof of a weak or rare hadith. mode=sources: every book recording one hadith_key, with its page_id, one row per book in index order. A downloaded:false book is catalogued but not installed: use another edition (shamela_get_details(kind='book') same_group). Narrator chains → shamela_lookup_rijal(mode='isnad_search'); general text → shamela_search(match='words').
| Argument | Type | Description |
|---|---|---|
| mode | string | Selects what the call does: search | sources. Default search. |
| limit | integer | Maximum number of results to return (1-100, default 20). (mode=search only.) |
| query | string | The hadith text (or a distinctive part of it). AND-combines words across matn + footnotes. Hadith keys come from each matching page's service annotations, takhrij from hadeeth.db. E.g. {query:'إنما الأعمال بالنيات'}. (mode=search only.) |
| hadith_key | integer | Numeric hadith key (the normalized identifier Shamela uses across collections — e.g. 1234). Different collections of the same hadith share this key. Take it from shamela_lookup_hadith(mode='search'), shamela_read(unit='services'), or the `hadeeth_key` of a chain from shamela_lookup_rijal(mode='isnad') / shamela_lookup_rijal(mode='isnad_search') (a string there; pass it as a number). Read from Shamela's pre-built service/hadeeth.db join, for cross-collection research (Bukhari, Muslim, the Sunan and Musnad references of one hadith); read each page with shamela_read(unit='page'). One row per book, in index order; `total` counts all, `returned` only those installed here unless downloaded_only:false. SERVICE_KEY_NOT_FOUND: no book has the key. Example: {hadith_key:1}. (mode=sources only.) |
Qur'an text. mode=search (default): find verses by Arabic words, typed in إملائي spelling or pasted in Uthmani rasm; words ANDed, results in mushaf order (aya_id 1–6236), not relevance. Zero hits usually means a misspelling: drop a word or use options.wildcards. mode=aya: fetch verses you can already cite, by aya_id OR surah + aya (never both or neither: BAD_ARG); `count` gives a run that continues across surahs and stops at the last verse. Each verse in three renderings (body = the spelling search matches, amiri for display). AYA_NOT_FOUND names the valid range. Commentary → shamela_lookup_tafsir; the words inside books → shamela_search(match='words').
| Argument | Type | Description |
|---|---|---|
| aya | integer | Aya number within the surah, 1..N. Pair with `surah`. (mode=aya only.) |
| mode | string | Selects what the call does: search | aya. Default search. |
| count | integer | How many consecutive verses to return, starting at the one resolved above (1-20, default 1). Use it for a passage — «the last two verses of al-Baqara» is surah=2, aya=285, count=2, and a short surah comes back in one call. The response always reports `surah_ayat`, that surah's total verse count, so you never have to guess how many to ask for. Verses continue across the surah boundary; each carries its own surah/aya. E.g. {surah:112, aya:1, count:4} = all of al-Ikhlas. (mode=aya only.) |
| limit | integer | Maximum number of results to return (1-100, default 20). (mode=search only.) |
| query | string |
Hadith narrators and isnad chains, from Shamela's rijal register and isnad index. `mode`: - narrators (default): a narrator by name → narrator_id, most-documented first, then earliest death year. Names collide: confirm the death year before using an id. - narrator: one dossier by narrator_id — lineage, death year, tabaqa, Ibn Hajar's and al-Dhahabi's grades, critics' jarh wa-ta'dil verdicts verbatim with source (the only paged part), hadith_notes on audition and irsal; include_network adds isnad-index counts per book and top teachers/students. Quote verdicts as worded; never synthesize a grade. - isnad_search: chains by the narrators in them — `contains` (anywhere) or `transmission` [teacher_id, student_id] pairs that must be adjacent (direct audition, the stronger test) — each hit with book, page, hadeeth_key and the chain. - isnad: the chain(s) printed on one page (book_id/page_id from a search hit) with names and death years, plus the same hadith's other routes — one thread or many. Rules: a parameter of another mode is refused. Chains run ascending (Companion first, collector last). Only ten hadith books are isnad-indexed (see scope_book_ids): an empty isnad_search means no such chain in those ten, not in all literature; most pages answer no_isnad_indexed:true with a no_isnad_reason, not an error. Errors: RIJAL_UNAVAILABLE (register not installed), NARRATOR_NOT_FOUND (search the name again), BOOK_NOT_FOUND, PAGE_NOT_FOUND, BOOK_NOT_DOWNLOADED (try shamela_get_details(kind='book') same_group). Instead: book authors → shamela_find(kind='author'); a hadith by its text → shamela_lookup_hadith(mode='search').
| Argument | Type | Description |
|---|---|---|
| mode | string | Selects what the call does: narrators | narrator | isnad_search | isnad. Default narrators. |
| limit | integer | [mode=narrators] Maximum narrators to return (1-50, default 10). [mode=narrator] How many CRITICS of al-jarḥ wa-l-taʿdīl to return (1-100, default 10) — the only part of the dossier that is paged. al-Zuhrī has 56 critics and 184 verdicts; they do not fit one response, and `total_critics` says how many there are. (mode=narrators|narrator only.) |
Tafsir on one verse (aya_id OR surah + aya, else BAD_ARG). mode=coverage (default): which tafsir books cover it, fetching no text — shelves 3 (tafsir) and 4 (Qur'anic sciences; not 5, tajwid and qira'at) crossed with Shamela's curated tafsir index, plus index hits from other shelves (in_tafsir_categories:false). Status per book: indexed_covers (with page_id), indexed_no_entry_for_this_aya, or not_indexed_coverage_unknown — NOT evidence the book is silent. mode=texts: the commentary from several books in one call, each attributed (book, author, death year, printed page), read only from pages the index maps to the verse, never a text-search guess. Each source's `note` names the next call when its text continues. Example: {surah:2, aya:255, book_ids:[1503, 639]}.
| Argument | Type | Description |
|---|---|---|
| aya | integer | Verse number within the surah, 1..N; requires `surah`. |
| mode | string | Selects what the call does: coverage | texts. Default coverage. |
| surah | integer | Surah number 1..114; requires `aya`. Alternative to aya_id. |
| aya_id | integer | Cumulative verse id, 1..6236 (e.g. 262 = 2:255). Give this OR surah + aya, not both; a reference that disagrees with surah/aya is BAD_ARG. |
| book_ids | array | Restrict to these tafsir books, read in the order given (omit it and the installed indexed books are read earliest author first). Books not present in the curated index for this aya are reported with an explicit status instead of text. Use shamela_lookup_tafsir(mode='coverage') to see which books the index covers. (mode=texts only.) |
Read an installed book's text and structure by internal ids. `unit`: - page (default): one page_id → body (author's matn), foot (editor's footnotes), printed page label, prev/next page ids, enclosing headings. - range: up to 20 consecutive pages from start_page_id, each with text, footnotes, printed page — to read on past a hit or through a span. - section: one chapter by title_id with its sub-headings, up to the next heading outside it. - toc: headings with their title_ids; top level by default, parent_id/depth expand, containing_page_id gives the chain enclosing a page. - parts: volumes — part label, page count, first/last page_id. - services: what one page cites (aya ids, hadith keys, isnad markers, as stored) → shamela_lookup_quran(mode='aya'), shamela_lookup_hadith(mode='sources'), shamela_lookup_rijal(mode='isnad'). Rules: a parameter of another unit is refused. page_id is not the printed page and ids have gaps: step with prev_page_id/next_page_id, not ±1; for a printed «vol./page» call shamela_cite(mode='printed_page') first. A size budget cuts long text: follow body_has_more (body_part+1) or next_start_page_id. Errors: PAGE_NOT_FOUND (also a range start past the end), TITLE_NOT_FOUND, BOOK_NOT_FOUND, BOOK_NOT_DOWNLOADED (catalogued, not installed: use an installed edition from shamela_get_details(kind='book') same_group). Instead: a heading by its words → shamela_find(kind='heading'); books of untitled «فصل» headings → shamela_search(match='words') scoped to the book; any catalogued book's metadata → shamela_get_details(kind='book').
| Argument | Type | Description |
|---|---|---|
| unit | string | Selects what the call does: page | range | section | toc | parts | services. Default page. |
| count | integer | How many consecutive pages to fetch (1–20, default 5). Fewer come back when the ~12,000-character budget is reached; has_more then stays true. Use shamela_read(unit='section') for full chapter reads. Faster than looping unit='page'. E.g. {unit:'range', book_id, start_page_id:1, count:5}. (unit=range only.) |
Full-text search inside the pages (matn and footnotes) of installed books. `match` picks how the query is read: - words (default): every word required, ranked by relevance; options add morphology, wildcards, chronological sort. An all-words miss retries with fewer words (relaxed_min_match). - phrase: the words consecutively (a quotation). near: all words within `distance`, any order. Both verified in the full page text. - exact: diacritics, hamza/alef forms or digit systems kept distinct («أحمد» not «احمد», «عِلْم» not «عَلَم», ٢٥٥ not 255); set at least one `preserve` flag. - boolean: every all_of term, one or more any_of, no none_of (الوقف with المسجد or المقبرة, without البيع); one query over the whole index, so total_hits is exact and exclusion exhaustive. - batch: 1–24 scoped `queries` run at once, merged and deduped by page (probe_ids); no paging, cut at max_total_passages. Rules: a parameter of another match value is refused. Page with limit/offset until has_more is false. scope.madhab drops books of unknown school: omit it for comparative questions; set scope.citable_only before quoting a page number. Follow-up rounds: exclude_pages / exclude_work_group_ids keep out pages already used and other printings of the same work. EMPTY_SCOPE: the scope matched no book. Instead: chapter headings → shamela_find(kind='heading'); titles → shamela_find(kind='book'); verses → shamela_lookup_quran(mode='search'); a hadith's wording → shamela_lookup_hadith(mode='search'). Example: {query:'استصناع', scope:{category_ids:[17]}}.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return (1-100, default 20). (match=words|phrase|near|exact|boolean only.) |
| match | string | Selects what the call does: words | phrase | near | exact | boolean | batch. Default words. |
| query | string |
Search one named shelf of the classical Islamic library (8,594 works) for quotable passages: verbatim Arabic with book, author, printed volume/page, edition and a shamela.ws link. The default first search for hadith, tafsir, fiqh or creed. Not for isnads, narrators or diacritic-exact wording. Use shamela_search (match "words") to pin books or categories or to page past 10 results, shamela_read (unit "page") to read a whole page. Scope is one shelf per call; call again with another shelf to widen. Ranking: exact phrase first, then all the words; a madhhab scope asks that school's own books first; main text before footnote. relaxedToTokens and note flag a weaker match; no passages means absent from that scope, not from the library. A non-Arabic query or unknown scope returns a tool error naming the fix.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum passages to return (max 10). |
| query* | string | Arabic search text. A quoted wording works best; a topic also works. |
| scope* | string | hadith-primary — The eight primary hadith collections, edition-pinned; tafsir-canonical — Canonical tafsir — Ibn Kathir, al-Tabari, Ibn al-Jawzi first; fiqh-hanafi — Hanafi fiqh (+ usul, comparative); fiqh-maliki — Maliki fiqh (+ usul, comparative); fiqh-shafii — Shafi'i fiqh (+ usul, comparative); fiqh-hanbali — Hanbali fiqh (+ usul, comparative); fiqh-comparative — All four schools plus comparative and fatwa collections; aqeedah — Creed and sects; hadith-sciences — Hadith commentary, takhrij and the sciences of hadith; tafsir — The whole tafsir shelf and Quranic sciences; seerah — Prophetic biography, history and biographical dictionaries; lugha — Arabic language, lexicons, grammar and adab |
Count how much the library holds on a term and where: the exact matching-page total plus its distribution by category, Hijri century, book and author (top 15 each). Statistics only, never passages — use shamela_search(match='words') instead to retrieve and read the pages. Run it before searching to size a topic and pick scope.category_ids (map by_category names to ids with shamela_find(kind='category')). mode 'literal' (default, 6–9 ms) counts the word as written; 'morphological' counts every derived form of its root (seconds) and is often far broader. coverage_capped:true means the breakdown is a top-5,000 sample whose counts are floors; total_hits stays exact. No match = total_hits 0; EMPTY_SCOPE when scope matches no book. Example: {term:'الاستصناع', scope:{category_ids:[14,15,16,17]}}; {term:'التيمم', scope:{citable_only:true}}.
| Argument | Type | Description |
|---|---|---|
| mode | string | 'literal' counts pages carrying the WORD as written (plus the ordinary spelling folds). 'morphological' expands it to every AlKhalil root reading and counts those — which is far broader than most callers expect: «الاستصناع» reports 393,498 pages across 7,405 books morphologically against 1,510 literally, an answer that says every shelf holds the topic. Use 'literal' to size a topic before planning retrieval; use 'morphological' to trace a ROOT through its derivations. |
| term* | string | Arabic word or root to profile (e.g. «الاستصناع»، «صبر»، «رحم»). Under mode='literal' (default) only the word as written is counted; under mode='morphological' it is matched via the AlKhalil analyzer, so all derived forms (صابر، يصبر، اصطبار…) are counted, not just the literal string. |
| scope | object | Restrict the profile to specific books, authors, categories, or a Hijri date range. Use shamela_find(kind='category') / shamela_find(kind='name') to find IDs. Omit to profile the whole library installed on this server. |
| style | string | Citation style. 'shamela' replicates Shamela's UI copy-with-citation format (default). 'short' is a one-line inline reference. 'full' is the long form including author death year and book year, with notes listing missing fields (publisher/edition/etc are not in master.db). 'bibtex' and 'ris' are machine-readable exports for Zotero/EndNote/Mendeley (Western digits, Arabic UTF-8, stable cite key shamela<book_id>p<page_id>); they carry only fields master.db has, with the same missing-field notes[]. 'short' reads <author>، <book>، ص <page>. Every style but bibtex/ris uses Arabic-Indic digits. (mode=citation only.) |
| book_id | integer | [mode=citation] The book id, from shamela_find(kind='book'), shamela_find(kind='work') or shamela_find(kind='name'). [mode=printed_page] The book. Resolve a cited title with shamela_find(kind='work') first — and note that different printings of one work paginate differently, so the book_id must be the printing the citation came from. |
| page_id | integer | Optional page_id. When omitted, the citation references the book without a specific page and page_resolved is null. A page id that is missing, has no printed number, or belongs to a book whose text is not installed here yields a book-level citation with page_resolved:false and a note. Example: {book_id:1681, page_id:10}, or with text:'<quoted passage>', style:'shamela'. (mode=citation only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"mode": {
"enum": [
"citation",
"printed_page"
],
"type": "string",
"description": "Selects what the call does: citation | printed_page. Default citation."
},
"page": {
"type": "integer",
"minimum": 1,
"description": "The PRINTED page number as the citation gives it (e.g. 405). Example: {book_id:6910, part:'4', page:405}; {book_id:1681, part:'1', page:6}. (mode=printed_page only.)"
},
"part": {
"type": "string",
"description": "The volume/part label as the book uses it, usually a bare number ('4'). Omit when the citation names no volume or the work is single-volume: the search then runs across every part and the response reports which parts matched, so an ambiguous page number is visible rather than silently resolved to the first volume. (mode=printed_page only.)"
},
"text": {
"type": "string",
"description": "Optional quoted text. Used by the 'shamela' style only, which then prints a two-line block: «<book>» (<part>/ <page>):\n«<text>». Other styles ignore it. (mode=citation only.)"
},
"style": {
"enum": [
"shamela",
"short",
"full",
"bibtex",
"ris"
],
"type": "string",
"description": "Citation style. 'shamela' replicates Shamela's UI copy-with-citation format (default). 'short' is a one-line inline reference. 'full' is the long form including author death year and book year, with notes listing missing fields (publisher/edition/etc are not in master.db). 'bibtex' and 'ris' are machine-readable exports for Zotero/EndNote/Mendeley (Western digits, Arabic UTF-8, stable cite key shamela<book_id>p<page_id>); they carry only fields master.db has, with the same missing-field notes[]. 'short' reads <author>، <book>، ص <page>. Every style but bibtex/ris uses Arabic-Indic digits. (mode=citation only.)"
},
"book_id": {
"type": "integer",
"description": "[mode=citation] The book id, from shamela_find(kind='book'), shamela_find(kind='work') or shamela_find(kind='name'). [mode=printed_page] The book. Resolve a cited title with shamela_find(kind='work') first — and note that different printings of one work paginate differently, so the book_id must be the printing the citation came from.",
"exclusiveMinimum": 0
},
"page_id": {
"type": "integer",
"description": "Optional page_id. When omitted, the citation references the book without a specific page and page_resolved is null. A page id that is missing, has no printed number, or belongs to a book whose text is not installed here yields a book-level citation with page_resolved:false and a note. Example: {book_id:1681, page_id:10}, or with text:'<quoted passage>', style:'shamela'. (mode=citation only.)",
"exclusiveMinimum": 0
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}| limit | integer | [kind=book|heading|author|period] Maximum number of results to return (1-100, default 20). [kind=work] Maximum candidates to report (1-50, default 20). [kind=name] Maximum results per list (1–20, default 5): with type 'any' you get up to `limit` books AND up to `limit` authors. (kind=book|heading|author|work|name|period only.) |
| query | string | [kind=book] Arabic words matched against book name + author + bibliography and the editorial subject description; each hit's `matched_in` says which. 1,729 entries carry a description (~1,500 characters on average), which finds a book by SUBJECT: «الرجز» matches 0 titles and 2 descriptions; {query:'البيوع'} also returns books whose description carries it. E.g. {query:'الأصول'}. [kind=heading] Arabic words matched against chapter / section title text, e.g. 'باب الصيام', or 'تعريف' with scope:{book_ids:[id]}. [kind=author] Arabic words matched against name + biography in the ~3,200-author catalogue, e.g. 'ابن قدامة'. [kind=name] An Arabic name fragment: 'ابن قدامة' resolves Ibn Qudamah, 'روضة الناظر' the book, 'الروضة' the books with that word in their title; «title لِauthor» is split into title and author. Every kind reads pre-built indexes: no download needed. (kind=book|heading|author|name only.) |
| scope | object | [kind=book] Restrict to authors, categories, a Hijri period (period_from/period_to) or downloaded_only (books whose text is installed); scope.book_ids is not accepted. E.g. {query:'فقه', scope:{category_ids:[17], downloaded_only:true}}. [kind=heading] The same filter as shamela_search(match='words'); scope.book_ids with one id searches only that book's headings. EMPTY_SCOPE: the scope matched no book. (kind=book|heading only.) |
| title | string | The work's title as cited, e.g. «صحيح البخاري», «المغني», «فتح الباري». Leading words only — the title, not a description of it. You may include the catalogue's own edition tail, with the « - » («صحيح البخاري - ط السلطانية») or without it («مسند أحمد ط الرسالة»), and it will be read as `edition`. An author name appended instead («صحيح البخاري محمد بن إسماعيل البخاري», «الهداية للمرغيناني») is read as `author`. Where a title is held by more than one author, a trailing edition is NOT read as one until you also pass `author` — «صحيح البخاري ت البغا» alone is refused, «صحيح البخاري ت البغا» + author «البخاري» resolves. The title must be a PREFIX of the entry's own: «شرح صحيح البخاري», «المدخل إلى صحيح البخاري» and «عمدة القاري شرح صحيح البخاري» contain the work's name and none IS the work. A commentary is rejected (listed in rejected[]): quoting it as the work would attribute its author's words to al-Bukhari. Example: {title:'المغني', author:'ابن قدامة'}. (kind=work only.) |
| author | string | The author as cited, when known. This is a FILTER, not a hint: a candidate whose author cannot be reconciled with it is rejected rather than ranked down, because that is exactly how a commentary gets returned as the work it comments on. (kind=work only.) |
| offset | integer | Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (kind=book|heading|author|period only.) |
| died_to | integer | Hijri year, inclusive UPPER bound on the MAIN AUTHOR's death year (author.death_number). Pair with died_from. (kind=period only.) |
| edition | string | A specific printing, as the catalogue names it: 'ط السلطانية', 'ت البغا', 'ط التأصيل'. If no entry carries it you get status='not_found' with reason='edition_not_found' and the editions that DO exist — never a different book. (kind=work only.) |
| options | object | [kind=book] morphology / wildcards / sort / relax_when_empty. [kind=heading] morphology / wildcards / sort ('chronological' = earliest author first); headings are matched in folded form only. [kind=author] morphology / wildcards / sort ('relevance' by default; 'chronological' = by Hijri death year, earliest first, undated last), e.g. {query:'الشافعي', options:{wildcards:false}}. preserve_* return OPTION_NOT_SUPPORTED; search_in is ignored (catalogue entries have no body or footnotes; a heading is a single field). Results are ranked by relevance unless sort says otherwise. (kind=book|heading|author only.) |
| died_from | integer | Hijri year, inclusive LOWER bound on the MAIN AUTHOR's death year (author.death_number). A different column from composed_*, but the same number on 98.5% of dated books. Pair with died_to. At least one of composed_from/composed_to/died_from/died_to is required (BAD_ARG); a missing side is open-ended, and undated books drop out under any bound set. E.g. died_from:700, died_to:800 = 8th-century-Hijri authors. A composed-vs-died question («written in the 8th century by authors who died in the 9th») cannot be answered from this data: a near-empty result means the distinction is unavailable, not that no such book exists. (kind=period only.) |
| category_id | integer | Optional: restrict to one category (use shamela_find(kind='category') for IDs). Categories are flat in master.db. Example: {died_from:600, died_to:700, category_id:17}. (kind=period only.) |
| composed_to | integer | Hijri year, inclusive UPPER bound on book.book_date («تاريخ الكتاب»; see composed_from — it is not a composition year). Pair with composed_from. (kind=period only.) |
| composed_from | integer | Hijri year, inclusive LOWER bound on book.book_date — Shamela's «تاريخ الكتاب». NOT an independent composition year: it holds the main author's death year on 98.5% of dated books (8,461/8,587), so pairing it with died_* almost never narrows anything. Pair with composed_to. (kind=period only.) |
| include_counts | boolean | If true (default), include book_count for each category; false returns book_count 0. Costs nothing either way — counts are precomputed. downloaded_count is always filled. (kind=category only.) |
| downloaded_only | boolean | [kind=category] If true, list only categories with at least one book installed on this server. Useful to see where the installed library is concentrated across the 41 categories. Default: false. [kind=period] If true, restrict to books whose text is installed on this server — the only ones with searchable page content. Default false lists the whole catalogue. (kind=category|period only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kind": {
"enum": [
"book",
"heading",
"author",
"category",
"work",
"name",
"period"
],
"type": "string",
"description": "Selects what the call does: book | heading | author | category | work | name | period. Default book."
},
"type": {
"enum": [
"any",
"book",
"author"
],
"type": "string",
"description": "'book' matches catalogue titles only, 'author' author names only, 'any' (default) both, returned as separate books[] and authors[] lists. Reads the s_book/ and s_author/ n-gram indexes (fast partial matching). Example: {query:'ابن قدامة', type:'author'}. (kind=name only.)"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "[kind=book|heading|author|period] Maximum number of results to return (1-100, default 20). [kind=work] Maximum candidates to report (1-50, default 20). [kind=name] Maximum results per list (1–20, default 5): with type 'any' you get up to `limit` books AND up to `limit` authors. (kind=book|heading|author|work|name|period only.)"
},
"query": {
"type": "string",
"minLength": 1,
"description": "[kind=book] Arabic words matched against book name + author + bibliography and the editorial subject description; each hit's `matched_in` says which. 1,729 entries carry a description (~1,500 characters on average), which finds a book by SUBJECT: «الرجز» matches 0 titles and 2 descriptions; {query:'البيوع'} also returns books whose description carries it. E.g. {query:'الأصول'}. [kind=heading] Arabic words matched against chapter / section title text, e.g. 'باب الصيام', or 'تعريف' with scope:{book_ids:[id]}. [kind=author] Arabic words matched against name + biography in the ~3,200-author catalogue, e.g. 'ابن قدامة'. [kind=name] An Arabic name fragment: 'ابن قدامة' resolves Ibn Qudamah, 'روضة الناظر' the book, 'الروضة' the books with that word in their title; «title لِauthor» is split into title and author. Every kind reads pre-built indexes: no download needed. (kind=book|heading|author|name only.)"
},
"scope": {
"type": "object",
"properties": {
"madhab": {
"type": "array",
"items": {
"enum": [
"hanafi",
"maliki",
"shafii",
"hanbali"
],
"type": "string"
},
"description": "Restrict to books of these Sunni schools. master.db has NO madhab field, so this is resolved two ways: a book filed under a school-specific category (الفقه الحنفي/المالكي/الشافعي/الحنبلي) counts directly, and otherwise the MAIN AUTHOR's school is used, inferred from the categories that author's own books are filed under. That second path is what reaches مسائل فقهية and الفقه العام, where Shamela records no school — it raises madhab coverage of the fiqh shelves from 27% to 43%. Books whose school cannot be established are EXCLUDED by this filter, so do not read absence as 'no school said this'; for comparative questions leave madhab unset and scope by category instead."
},
"book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to these book IDs. Use `shamela_find(kind='name')` or `shamela_list_downloaded_books` to find IDs. Combine with other scope keys for intersection."
},
"book_type": {
"type": "array",
"items": {
"enum": [
"book",
"journal",
"manuscript",
"thesis",
"electronic",
"transcript"
],
"type": "string"
},
"description": "Restrict to these kinds of entry (master.db.book.book_type — the same filter row Shamela's own 'اختيار كتاب' window shows). 'transcript' (تفريغات) is a transcribed lecture series, not an authored book, and 'thesis'/'electronic' are likewise not printed works — excluding them sharpens a scholarly search. Of 8,594 entries, 7,334 are 'book'; 1,260 are not."
},
"period_to": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive upper bound. Pair with period_from."
},
"author_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books by these authors. Includes co-authored books. Use `shamela_find(kind='name', type='author')` to find IDs."
},
"period_from": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive lower bound. Matches book.book_date (composition year) OR author.death_number (death year). Pair with period_to."
},
"category_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books in these categories. Categories are flat in master.db (no parent_id, no transitive subtree expansion). Use `shamela_find(kind='category')` to find IDs."
},
"citable_only": {
"type": "boolean",
"description": "Keep only books whose page numbering matches a real printed edition (master.db.book.printed == 1 — Shamela's «يوافق المطبوع»). The other 1,417 entries are paginated by Shamela automatically, so their page numbers are NOT a citable reference to any published edition. Set this true whenever the answer will quote a page number as a citation. Default: false."
},
"downloaded_only": {
"type": "boolean",
"description": "Restrict to books actually downloaded on this user's machine (master.db.book.major_ondisk > 0). Critical for honest research scoping when using `shamela_search(match='words')` — only downloaded books have searchable content. Default: false."
}
},
"description": "[kind=book] Restrict to authors, categories, a Hijri period (period_from/period_to) or downloaded_only (books whose text is installed); scope.book_ids is not accepted. E.g. {query:'فقه', scope:{category_ids:[17], downloaded_only:true}}. [kind=heading] The same filter as shamela_search(match='words'); scope.book_ids with one id searches only that book's headings. EMPTY_SCOPE: the scope matched no book. (kind=book|heading only.)",
"additionalProperties": false
},
"title": {
"type": "string",
"minLength": 1,
"description": "The work's title as cited, e.g. «صحيح البخاري», «المغني», «فتح الباري». Leading words only — the title, not a description of it. You may include the catalogue's own edition tail, with the « - » («صحيح البخاري - ط السلطانية») or without it («مسند أحمد ط الرسالة»), and it will be read as `edition`. An author name appended instead («صحيح البخاري محمد بن إسماعيل البخاري», «الهداية للمرغيناني») is read as `author`. Where a title is held by more than one author, a trailing edition is NOT read as one until you also pass `author` — «صحيح البخاري ت البغا» alone is refused, «صحيح البخاري ت البغا» + author «البخاري» resolves. The title must be a PREFIX of the entry's own: «شرح صحيح البخاري», «المدخل إلى صحيح البخاري» and «عمدة القاري شرح صحيح البخاري» contain the work's name and none IS the work. A commentary is rejected (listed in rejected[]): quoting it as the work would attribute its author's words to al-Bukhari. Example: {title:'المغني', author:'ابن قدامة'}. (kind=work only.)"
},
"author": {
"type": "string",
"description": "The author as cited, when known. This is a FILTER, not a hint: a candidate whose author cannot be reconciled with it is rejected rather than ranked down, because that is exactly how a commentary gets returned as the work it comments on. (kind=work only.)"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (kind=book|heading|author|period only.)"
},
"died_to": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive UPPER bound on the MAIN AUTHOR's death year (author.death_number). Pair with died_from. (kind=period only.)"
},
"edition": {
"type": "string",
"description": "A specific printing, as the catalogue names it: 'ط السلطانية', 'ت البغا', 'ط التأصيل'. If no entry carries it you get status='not_found' with reason='edition_not_found' and the editions that DO exist — never a different book. (kind=work only.)"
},
"options": {
"type": "object",
"properties": {
"sort": {
"enum": [
"relevance",
"chronological"
],
"type": "string",
"description": "Result order. 'relevance' (default) ranks by how well the page matches — the right answer to 'find me X'. 'chronological' orders by the author's death year, then book, then page, so the EARLIEST sources come first — the right answer to 'who says this first' or 'how does this idea travel through the tradition'. Undated books sort last."
},
"search_in": {
"type": "array",
"items": {
"enum": [
"body",
"foot"
],
"type": "string"
},
"description": "Ignored here. Default: ['body','foot']."
},
"wildcards": {
"type": "boolean",
"description": "Interpret `*` (zero-or-more characters) and `?` (exactly-one character) within tokens. Examples: `صيا*` matches صيام/صيامهم, `ص?م` matches صام/صوم/صمم. Leading wildcards (`*ابن`) are slow. Cannot combine with `morphology`. With this OFF, `*` and `?` are treated as ordinary punctuation and split the word, so a stray one no longer zeroes the search. CAVEAT on prefixes: the index folds some words as a WHOLE — «مائة» is stored as «ميه», «داوود» as «داود» — and a wildcard stem is folded without the letters the wildcard replaced, so `مائ*` becomes `ماي*` and reaches مائع/مائدة but NOT مائة. When a prefix search returns less than you expect for a word like these, search the full word without a wildcard instead. Default: false."
},
"morphology": {
"type": "boolean",
"description": "Search Arabic root forms via the AlKhalil morphological analyzer. Useful when looking for all word forms (يكتب، كاتب، مكتوب…) of a root (كتب). Cannot be combined with `wildcards`. Default: false."
},
"preserve_hamza": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here. Default: false."
},
"preserve_digits": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here. Default: false."
},
"relax_when_empty": {
"type": "boolean",
"description": "When the AND of every word of the title matches no catalogue entry, retry requiring only the largest number of them some entry does carry, and report it in `relaxed_min_match`. A title is usually quoted the way people cite it («فتح الباري لابن حجر») rather than the way the catalogue spells it («فتح الباري بشرح البخاري - ط السلفية»), and the strict AND then reports the library does not hold the book at all. Default: true."
},
"preserve_diacritics": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here. Default: false."
}
},
"description": "[kind=book] morphology / wildcards / sort / relax_when_empty. [kind=heading] morphology / wildcards / sort ('chronological' = earliest author first); headings are matched in folded form only. [kind=author] morphology / wildcards / sort ('relevance' by default; 'chronological' = by Hijri death year, earliest first, undated last), e.g. {query:'الشافعي', options:{wildcards:false}}. preserve_* return OPTION_NOT_SUPPORTED; search_in is ignored (catalogue entries have no body or footnotes; a heading is a single field). Results are ranked by relevance unless sort says otherwise. (kind=book|heading|author only.)",
"additionalProperties": false
},
"died_from": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive LOWER bound on the MAIN AUTHOR's death year (author.death_number). A different column from composed_*, but the same number on 98.5% of dated books. Pair with died_to. At least one of composed_from/composed_to/died_from/died_to is required (BAD_ARG); a missing side is open-ended, and undated books drop out under any bound set. E.g. died_from:700, died_to:800 = 8th-century-Hijri authors. A composed-vs-died question («written in the 8th century by authors who died in the 9th») cannot be answered from this data: a near-empty result means the distinction is unavailable, not that no such book exists. (kind=period only.)"
},
"category_id": {
"type": "integer",
"description": "Optional: restrict to one category (use shamela_find(kind='category') for IDs). Categories are flat in master.db. Example: {died_from:600, died_to:700, category_id:17}. (kind=period only.)",
"exclusiveMinimum": 0
},
"composed_to": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive UPPER bound on book.book_date («تاريخ الكتاب»; see composed_from — it is not a composition year). Pair with composed_from. (kind=period only.)"
},
"composed_from": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive LOWER bound on book.book_date — Shamela's «تاريخ الكتاب». NOT an independent composition year: it holds the main author's death year on 98.5% of dated books (8,461/8,587), so pairing it with died_* almost never narrows anything. Pair with composed_to. (kind=period only.)"
},
"include_counts": {
"type": "boolean",
"description": "If true (default), include book_count for each category; false returns book_count 0. Costs nothing either way — counts are precomputed. downloaded_count is always filled. (kind=category only.)"
},
"downloaded_only": {
"type": "boolean",
"description": "[kind=category] If true, list only categories with at least one book installed on this server. Useful to see where the installed library is concentrated across the 41 categories. Default: false. [kind=period] If true, restrict to books whose text is installed on this server — the only ones with searchable page content. Default false lists the whole catalogue. (kind=category|period only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kind": {
"enum": [
"book",
"author"
],
"type": "string",
"description": "Selects what the call does: book | author. Default book."
},
"book_id": {
"type": "integer",
"description": "The book id (e.g. 9942). (kind=book only.)",
"exclusiveMinimum": 0
},
"author_id": {
"type": "integer",
"description": "The author id (e.g. 474 for Ibn Qudama, 57 for Ibn Uthaymeen), from shamela_find(kind='name') with type 'author' or a book's authors[]. A catalogue id, not a death year or book id; shamela_find(kind='author') also gives it. (kind=author only.)",
"exclusiveMinimum": 0
},
"include_books": {
"type": "boolean",
"description": "If true (default), include every catalogued book by this author, main or co-author, ordered by book_id. False returns name and death year only. (kind=author only.)"
},
"include_cover": {
"type": "boolean",
"description": "Attach the book's cover image as an MCP image block when Shamela ships one (1,368 of 8,594 books). The picture is a ~310x460 thumbnail of the scanned printing's title page, so it costs roughly 190 image tokens. Set false to keep the reply text-only; `cover.available` still reports whether one exists. Default: true. (kind=book only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}| downloaded_only | boolean | If true (default), only return books whose text is installed on this server. false also lists catalogue-only editions (downloaded:false); `total` counts both either way. (mode=sources only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
| max_pages_scanned | integer | How many top text matches (by relevance) to scan for hadith service keys. This is the only result window: `matches` never exceeds it whatever `limit` says, and there is no offset. Default: 20. Raise it for a common wording. Key-bearing pages come first, then `limit` cuts. (mode=search only.) |
| search_all_categories | boolean | Search the ENTIRE library instead of the hadith shelves (كتب السنة، شروح الحديث، التخريج، علوم الحديث). Off by default because unscoped ranking buries the collections under works that merely quote the hadith. Turn on to find who CITES a hadith (e.g. in fiqh or tafsir) rather than who NARRATES it. (mode=search only.) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"mode": {
"enum": [
"search",
"sources"
],
"type": "string",
"description": "Selects what the call does: search | sources. Default search."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default 20). (mode=search only.)"
},
"query": {
"type": "string",
"minLength": 1,
"description": "The hadith text (or a distinctive part of it). AND-combines words across matn + footnotes. Hadith keys come from each matching page's service annotations, takhrij from hadeeth.db. E.g. {query:'إنما الأعمال بالنيات'}. (mode=search only.)"
},
"hadith_key": {
"type": "integer",
"description": "Numeric hadith key (the normalized identifier Shamela uses across collections — e.g. 1234). Different collections of the same hadith share this key. Take it from shamela_lookup_hadith(mode='search'), shamela_read(unit='services'), or the `hadeeth_key` of a chain from shamela_lookup_rijal(mode='isnad') / shamela_lookup_rijal(mode='isnad_search') (a string there; pass it as a number). Read from Shamela's pre-built service/hadeeth.db join, for cross-collection research (Bukhari, Muslim, the Sunan and Musnad references of one hadith); read each page with shamela_read(unit='page'). One row per book, in index order; `total` counts all, `returned` only those installed here unless downloaded_only:false. SERVICE_KEY_NOT_FOUND: no book has the key. Example: {hadith_key:1}. (mode=sources only.)",
"exclusiveMinimum": 0
},
"downloaded_only": {
"type": "boolean",
"description": "If true (default), only return books whose text is installed on this server. false also lists catalogue-only editions (downloaded:false); `total` counts both either way. (mode=sources only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
},
"max_pages_scanned": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "How many top text matches (by relevance) to scan for hadith service keys. This is the only result window: `matches` never exceeds it whatever `limit` says, and there is no offset. Default: 20. Raise it for a common wording. Key-bearing pages come first, then `limit` cuts. (mode=search only.)"
},
"search_all_categories": {
"type": "boolean",
"description": "Search the ENTIRE library instead of the hadith shelves (كتب السنة، شروح الحديث، التخريج، علوم الحديث). Off by default because unscoped ranking buries the collections under works that merely quote the hadith. Turn on to find who CITES a hadith (e.g. in fiqh or tafsir) rather than who NARRATES it. (mode=search only.)"
}
},
"additionalProperties": false
}| Arabic text of a verse or part of one. Matched against all 6,236 verses in BOTH orthographies — the Egyptian إملائي spelling a user types from memory AND the Uthmani rasm that mushaf apps, quran.com and PDFs copy (ٱ, dagger alef, ﴿﴾, full tashkeel are all handled), so paste the verse exactly as you received it. Every word is ANDed. Single-word queries also match prefixed forms (e.g. «الصبر» matches «بالصبر») AND the same word with «ال» stripped («الملك» is also searched as «ملك»/«للملك»), which widens the answer past the word you typed — the response names those forms in `stem_expanded_to`, tags each hit with the `matched_form` it came in on, and reports in `query_form_hits` how many verses match your word itself. Results come back in mushaf order (aya_id), not by relevance. Hafs from Asim text, pre-built aya/ Lucene index. (mode=search only.) |
| surah | integer | Surah number 1..114. Pair with `aya`. E.g. {surah:55, aya:1} = Ar-Rahman 1. (mode=aya only.) |
| aya_id | integer | Cumulative aya id, 1..6236. Mutually exclusive with surah/aya. E.g. 1 = al-Fatiha 1 (the basmala). (mode=aya only.) |
| offset | integer | Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (mode=search only.) |
| options | object | Currently only the `wildcards` flag is honored. The Quranic index ships pre-built and zero-config. `*` stands for any letters, `?` for one: {query:'الرحم*', options:{wildcards:true}} finds 57 verses. (mode=search only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"aya": {
"type": "integer",
"minimum": 1,
"description": "Aya number within the surah, 1..N. Pair with `surah`. (mode=aya only.)"
},
"mode": {
"enum": [
"search",
"aya"
],
"type": "string",
"description": "Selects what the call does: search | aya. Default search."
},
"count": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "How many consecutive verses to return, starting at the one resolved above (1-20, default 1). Use it for a passage — «the last two verses of al-Baqara» is surah=2, aya=285, count=2, and a short surah comes back in one call. The response always reports `surah_ayat`, that surah's total verse count, so you never have to guess how many to ask for. Verses continue across the surah boundary; each carries its own surah/aya. E.g. {surah:112, aya:1, count:4} = all of al-Ikhlas. (mode=aya only.)"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default 20). (mode=search only.)"
},
"query": {
"type": "string",
"minLength": 1,
"description": "Arabic text of a verse or part of one. Matched against all 6,236 verses in BOTH orthographies — the Egyptian إملائي spelling a user types from memory AND the Uthmani rasm that mushaf apps, quran.com and PDFs copy (ٱ, dagger alef, ﴿﴾, full tashkeel are all handled), so paste the verse exactly as you received it. Every word is ANDed. Single-word queries also match prefixed forms (e.g. «الصبر» matches «بالصبر») AND the same word with «ال» stripped («الملك» is also searched as «ملك»/«للملك»), which widens the answer past the word you typed — the response names those forms in `stem_expanded_to`, tags each hit with the `matched_form` it came in on, and reports in `query_form_hits` how many verses match your word itself. Results come back in mushaf order (aya_id), not by relevance. Hafs from Asim text, pre-built aya/ Lucene index. (mode=search only.)"
},
"surah": {
"type": "integer",
"maximum": 114,
"minimum": 1,
"description": "Surah number 1..114. Pair with `aya`. E.g. {surah:55, aya:1} = Ar-Rahman 1. (mode=aya only.)"
},
"aya_id": {
"type": "integer",
"maximum": 6236,
"minimum": 1,
"description": "Cumulative aya id, 1..6236. Mutually exclusive with surah/aya. E.g. 1 = al-Fatiha 1 (the basmala). (mode=aya only.)"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (mode=search only.)"
},
"options": {
"type": "object",
"properties": {
"wildcards": {
"type": "boolean",
"description": "Interpret `*` (zero-or-more characters) and `?` (exactly-one character) within tokens. Examples: `صيا*` matches صيام/صيامهم, `ص?م` matches صام/صوم/صمم. Leading wildcards (`*ابن`) are slow. Cannot combine with `morphology`. With this OFF, `*` and `?` are treated as ordinary punctuation and split the word, so a stray one no longer zeroes the search. CAVEAT on prefixes: the index folds some words as a WHOLE — «مائة» is stored as «ميه», «داوود» as «داود» — and a wildcard stem is folded without the letters the wildcard replaced, so `مائ*` becomes `ماي*` and reaches مائع/مائدة but NOT مائة. When a prefix search returns less than you expect for a word like these, search the full word without a wildcard instead. Default: false."
}
},
"description": "Currently only the `wildcards` flag is honored. The Quranic index ships pre-built and zero-config. `*` stands for any letters, `?` for one: {query:'الرحم*', options:{wildcards:true}} finds 57 verses. (mode=search only.)",
"additionalProperties": false
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}| query | string | Part of the narrator's name, in Arabic. Matched against the short name, the full lineage, and the register's الشهرة / اللقب / الكنية / النسب — so «الزهري» and «الأعمش» reach the men known by those nisbas even though neither appears in their recorded name. Folding is the same the page search uses, so «شعبه» finds «شعبة» and tashkeel is ignored. Tokens are ANDed and match anywhere, so «شعبة الحجاج» works even though the name reads «شعبة بن الحجاج». Results are ordered by how much al-jarḥ wa-l-taʿdīl the register holds on each man — the most-discussed «الزهري» first — with the earliest death year breaking ties. The register holds 18,989 narrators, died 2–774 AH. Names collide: check death year AND grade before deciding which «محمد بن إسماعيل» you have. E.g. 'شعبة بن الحجاج'. No hits: shorten or respell it. (mode=narrators only.) |
| top_n | integer | How many teachers and how many students to return, most frequent first (1-100, default 15). (mode=narrator only.) |
| offset | integer | [mode=narrators] Narrators to skip, for paging. Common names match in the thousands — «محمد بن» matches 4,271 — so page with this or narrow the query. Default: 0. [mode=narrator] Critics to skip, for paging through the verdicts. Follow `next_offset` until `has_more` is false. Default: 0. [mode=isnad_search] Chains to skip, for paging; follow `next_offset` while `has_more` is true. An offset past `paging_ceiling` returns no rows. Default: 0. (mode=narrators|narrator|isnad_search only.) |
| book_id | integer | Book id from a search hit (e.g. 1681, Sahih al-Bukhari). Chains exist only for the ten isnad-indexed books listed under shamela_lookup_rijal(mode='isnad_search'); other books answer no_isnad_indexed:true. (mode=isnad only.) |
| page_id | integer | Shamela page id within that book (not the printed page number), from the same hit. An id the book lacks is PAGE_NOT_FOUND. (mode=isnad only.) |
| contains | array | Narrator ids that must ALL appear in the chain, at any position and in any order. Use for «which reports pass through both X and Y». Ids from shamela_lookup_rijal(mode='narrators'). BAD_ARG when contains and transmission are both empty. E.g. {contains:[2779], scope_book_ids:[1681]} = Shu'ba's chains in al-Bukhari. (mode=isnad_search only.) |
| max_results | integer | Chains to return per page (1-100, default 20). Chains come in index order. (mode=isnad_search only.) |
| narrator_id | integer | The narrator id, as returned by shamela_lookup_rijal(mode='narrators') or inside a chain from shamela_lookup_rijal(mode='isnad'). Example: {narrator_id:4677}. (mode=narrator only.) |
| max_variants | integer | Cap on returned variant routes (1-200, default 20). `variants.truncated` reports when more exist. (mode=isnad only.) |
| transmission | array | Pairs [teacher_id, student_id] that must appear ADJACENT and in that order — direct transmission, the student having heard from the teacher with nobody in between. This is the question «did X really narrate from Y», and it is strictly stronger than listing both in `contains`. All pairs are ANDed. E.g. [[1580,2779]] = Shu'ba heard from al-Hakam b. Utayba; [[4677,4494]] = Umar to Alqama (20 chains). (mode=isnad_search only.) |
| scope_book_ids | array | Restrict to these books. The isnād index covers only ten: صحيح البخاري (1681), صحيح مسلم (711), سنن أبي داود (654), سنن الترمذي (7895), سنن النسائي (829), موطأ مالك (28107), مسند الطيالسي (1456), المنتقى لابن الجارود (627 و13071), وعلل الترمذي (642). 45,220 chains in all. (mode=isnad_search only.) |
| include_network | boolean | Include the transmission network computed from the isnād index: how many chains this narrator carries, in which books, and their most frequent teachers and students. Set false to skip it when you only need the biography. Default: true. (mode=narrator only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
| include_variants | boolean | Also return the other routes (طرق) of the same ḥadīth from the other indexed books, matched on Shamela's ḥadīth key. This is what shows whether a report rests on one thread or many. Default: true. (mode=isnad only.) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"mode": {
"enum": [
"narrators",
"narrator",
"isnad_search",
"isnad"
],
"type": "string",
"description": "Selects what the call does: narrators | narrator | isnad_search | isnad. Default narrators."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "[mode=narrators] Maximum narrators to return (1-50, default 10). [mode=narrator] How many CRITICS of al-jarḥ wa-l-taʿdīl to return (1-100, default 10) — the only part of the dossier that is paged. al-Zuhrī has 56 critics and 184 verdicts; they do not fit one response, and `total_critics` says how many there are. (mode=narrators|narrator only.)"
},
"query": {
"type": "string",
"minLength": 1,
"description": "Part of the narrator's name, in Arabic. Matched against the short name, the full lineage, and the register's الشهرة / اللقب / الكنية / النسب — so «الزهري» and «الأعمش» reach the men known by those nisbas even though neither appears in their recorded name. Folding is the same the page search uses, so «شعبه» finds «شعبة» and tashkeel is ignored. Tokens are ANDed and match anywhere, so «شعبة الحجاج» works even though the name reads «شعبة بن الحجاج». Results are ordered by how much al-jarḥ wa-l-taʿdīl the register holds on each man — the most-discussed «الزهري» first — with the earliest death year breaking ties. The register holds 18,989 narrators, died 2–774 AH. Names collide: check death year AND grade before deciding which «محمد بن إسماعيل» you have. E.g. 'شعبة بن الحجاج'. No hits: shorten or respell it. (mode=narrators only.)"
},
"top_n": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "How many teachers and how many students to return, most frequent first (1-100, default 15). (mode=narrator only.)"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "[mode=narrators] Narrators to skip, for paging. Common names match in the thousands — «محمد بن» matches 4,271 — so page with this or narrow the query. Default: 0. [mode=narrator] Critics to skip, for paging through the verdicts. Follow `next_offset` until `has_more` is false. Default: 0. [mode=isnad_search] Chains to skip, for paging; follow `next_offset` while `has_more` is true. An offset past `paging_ceiling` returns no rows. Default: 0. (mode=narrators|narrator|isnad_search only.)"
},
"book_id": {
"type": "integer",
"description": "Book id from a search hit (e.g. 1681, Sahih al-Bukhari). Chains exist only for the ten isnad-indexed books listed under shamela_lookup_rijal(mode='isnad_search'); other books answer no_isnad_indexed:true. (mode=isnad only.)",
"exclusiveMinimum": 0
},
"page_id": {
"type": "integer",
"description": "Shamela page id within that book (not the printed page number), from the same hit. An id the book lacks is PAGE_NOT_FOUND. (mode=isnad only.)",
"exclusiveMinimum": 0
},
"contains": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"description": "Narrator ids that must ALL appear in the chain, at any position and in any order. Use for «which reports pass through both X and Y». Ids from shamela_lookup_rijal(mode='narrators'). BAD_ARG when contains and transmission are both empty. E.g. {contains:[2779], scope_book_ids:[1681]} = Shu'ba's chains in al-Bukhari. (mode=isnad_search only.)"
},
"max_results": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Chains to return per page (1-100, default 20). Chains come in index order. (mode=isnad_search only.)"
},
"narrator_id": {
"type": "integer",
"minimum": 0,
"description": "The narrator id, as returned by shamela_lookup_rijal(mode='narrators') or inside a chain from shamela_lookup_rijal(mode='isnad'). Example: {narrator_id:4677}. (mode=narrator only.)"
},
"max_variants": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Cap on returned variant routes (1-200, default 20). `variants.truncated` reports when more exist. (mode=isnad only.)"
},
"transmission": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"maxItems": 2,
"minItems": 2
},
"description": "Pairs [teacher_id, student_id] that must appear ADJACENT and in that order — direct transmission, the student having heard from the teacher with nobody in between. This is the question «did X really narrate from Y», and it is strictly stronger than listing both in `contains`. All pairs are ANDed. E.g. [[1580,2779]] = Shu'ba heard from al-Hakam b. Utayba; [[4677,4494]] = Umar to Alqama (20 chains). (mode=isnad_search only.)"
},
"scope_book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to these books. The isnād index covers only ten: صحيح البخاري (1681), صحيح مسلم (711), سنن أبي داود (654), سنن الترمذي (7895), سنن النسائي (829), موطأ مالك (28107), مسند الطيالسي (1456), المنتقى لابن الجارود (627 و13071), وعلل الترمذي (642). 45,220 chains in all. (mode=isnad_search only.)"
},
"include_network": {
"type": "boolean",
"description": "Include the transmission network computed from the isnād index: how many chains this narrator carries, in which books, and their most frequent teachers and students. Set false to skip it when you only need the biography. Default: true. (mode=narrator only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
},
"include_variants": {
"type": "boolean",
"description": "Also return the other routes (طرق) of the same ḥadīth from the other indexed books, matched on Shamela's ḥadīth key. This is what shows whether a report rests on one thread or many. Default: true. (mode=isnad only.)"
}
},
"additionalProperties": false
}| max_sources | integer | Maximum number of sources to fetch text for (1-10, default 5). The response-size budget can stop earlier; `remaining_book_ids` lists the sources not read, to pass as book_ids next. (mode=texts only.) |
| downloaded_only | boolean | If true (default), list only books whose text is installed on this server. false also lists books the curated index maps to this aya whose text is not installed (downloaded:false) — still useful as catalogue references. (mode=coverage only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"aya": {
"type": "integer",
"minimum": 1,
"description": "Verse number within the surah, 1..N; requires `surah`."
},
"mode": {
"enum": [
"coverage",
"texts"
],
"type": "string",
"description": "Selects what the call does: coverage | texts. Default coverage."
},
"surah": {
"type": "integer",
"maximum": 114,
"minimum": 1,
"description": "Surah number 1..114; requires `aya`. Alternative to aya_id."
},
"aya_id": {
"type": "integer",
"maximum": 6236,
"minimum": 1,
"description": "Cumulative verse id, 1..6236 (e.g. 262 = 2:255). Give this OR surah + aya, not both; a reference that disagrees with surah/aya is BAD_ARG."
},
"book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to these tafsir books, read in the order given (omit it and the installed indexed books are read earliest author first). Books not present in the curated index for this aya are reported with an explicit status instead of text. Use shamela_lookup_tafsir(mode='coverage') to see which books the index covers. (mode=texts only.)"
},
"max_sources": {
"type": "integer",
"maximum": 10,
"minimum": 1,
"description": "Maximum number of sources to fetch text for (1-10, default 5). The response-size budget can stop earlier; `remaining_book_ids` lists the sources not read, to pass as book_ids next. (mode=texts only.)"
},
"downloaded_only": {
"type": "boolean",
"description": "If true (default), list only books whose text is installed on this server. false also lists books the curated index maps to this aya whose text is not installed (downloaded:false) — still useful as catalogue references. (mode=coverage only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}| depth | integer | Levels below parent_id to include (1–5, default 1); deeper levels arrive nested in `children`. Ignored when containing_page_id is set. E.g. {unit:'toc', book_id, depth:1} lists the top-level chapters. (unit=toc only.) |
| book_id | integer | The book id, from shamela_find(kind='book'), shamela_find(kind='work') or shamela_find(kind='name'). Installed ids: shamela_list_downloaded_books. |
| page_id | integer | [unit=page] Internal page id, as search hits, shamela_read(unit='toc') and shamela_cite(mode='printed_page') return it; not the printed page number. Ids have gaps, so take neighbours from prev_page_id/next_page_id. [unit=services] Shamela's internal page id (from a search hit or reader tool), not the printed page number. Example: {unit:'services', book_id:1681, page_id:10}. (unit=page|services only.) |
| title_id | integer | The title id of the chapter / section to fetch, from shamela_read(unit='toc') or shamela_find(kind='heading'). Its sub-headings are included. (unit=section only.) |
| body_part | integer | For long pages: when the body exceeds ~4000 characters it is split into parts. Pass the 1-based part to read (default 1). The response reports body_part/body_total_parts/body_has_more; request the next part by incrementing. The footnote/comment are returned with part 1. (unit=page only.) |
| keep_html | boolean | [unit=page] If true, preserve inline HTML markers (e.g. <span data-type='title'>). Default false strips them for plain Arabic display. [unit=range|section] If true, keep Shamela's inline markup: <span data-type='title'> headings, <a href="inr://man-<narrator_id>"> narrator links, <hadeeth-N> markers. Default false strips them for plain Arabic display. (unit=page|range|section only.) |
| max_pages | integer | Cap on pages to read (1–100, default 30). The ~12,000-character budget can stop the read earlier; either way truncated:true and next_start_page_id say where to resume with shamela_read(unit='range'). (unit=section only.) |
| parent_id | integer | Title id whose children to list; 0 (default) = top-level chapters. Ignored when containing_page_id is set. (unit=toc only.) |
| start_page_id | integer | First page id to read (inclusive). To continue a range that was cut short, pass the previous response's next_start_page_id. (unit=range only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
| containing_page_id | integer | Page id. Switches to ancestor-chain mode: returns the headings that enclose this page, root to leaf, in `ancestor_chain`; parent_id and depth are then ignored. E.g. containing_page_id:17 gives the chapter holding page 17. (unit=toc only.) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"unit": {
"enum": [
"page",
"range",
"section",
"toc",
"parts",
"services"
],
"type": "string",
"description": "Selects what the call does: page | range | section | toc | parts | services. Default page."
},
"count": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "How many consecutive pages to fetch (1–20, default 5). Fewer come back when the ~12,000-character budget is reached; has_more then stays true. Use shamela_read(unit='section') for full chapter reads. Faster than looping unit='page'. E.g. {unit:'range', book_id, start_page_id:1, count:5}. (unit=range only.)"
},
"depth": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"description": "Levels below parent_id to include (1–5, default 1); deeper levels arrive nested in `children`. Ignored when containing_page_id is set. E.g. {unit:'toc', book_id, depth:1} lists the top-level chapters. (unit=toc only.)"
},
"book_id": {
"type": "integer",
"description": "The book id, from shamela_find(kind='book'), shamela_find(kind='work') or shamela_find(kind='name'). Installed ids: shamela_list_downloaded_books.",
"exclusiveMinimum": 0
},
"page_id": {
"type": "integer",
"description": "[unit=page] Internal page id, as search hits, shamela_read(unit='toc') and shamela_cite(mode='printed_page') return it; not the printed page number. Ids have gaps, so take neighbours from prev_page_id/next_page_id. [unit=services] Shamela's internal page id (from a search hit or reader tool), not the printed page number. Example: {unit:'services', book_id:1681, page_id:10}. (unit=page|services only.)",
"exclusiveMinimum": 0
},
"title_id": {
"type": "integer",
"description": "The title id of the chapter / section to fetch, from shamela_read(unit='toc') or shamela_find(kind='heading'). Its sub-headings are included. (unit=section only.)",
"exclusiveMinimum": 0
},
"body_part": {
"type": "integer",
"minimum": 1,
"description": "For long pages: when the body exceeds ~4000 characters it is split into parts. Pass the 1-based part to read (default 1). The response reports body_part/body_total_parts/body_has_more; request the next part by incrementing. The footnote/comment are returned with part 1. (unit=page only.)"
},
"keep_html": {
"type": "boolean",
"description": "[unit=page] If true, preserve inline HTML markers (e.g. <span data-type='title'>). Default false strips them for plain Arabic display. [unit=range|section] If true, keep Shamela's inline markup: <span data-type='title'> headings, <a href=\"inr://man-<narrator_id>\"> narrator links, <hadeeth-N> markers. Default false strips them for plain Arabic display. (unit=page|range|section only.)"
},
"max_pages": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Cap on pages to read (1–100, default 30). The ~12,000-character budget can stop the read earlier; either way truncated:true and next_start_page_id say where to resume with shamela_read(unit='range'). (unit=section only.)"
},
"parent_id": {
"type": "integer",
"minimum": 0,
"description": "Title id whose children to list; 0 (default) = top-level chapters. Ignored when containing_page_id is set. (unit=toc only.)"
},
"start_page_id": {
"type": "integer",
"description": "First page id to read (inclusive). To continue a range that was cut short, pass the previous response's next_start_page_id. (unit=range only.)",
"exclusiveMinimum": 0
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
},
"containing_page_id": {
"type": "integer",
"description": "Page id. Switches to ancestor-chain mode: returns the headings that enclose this page, root to leaf, in `ancestor_chain`; parent_id and depth are then ignored. E.g. containing_page_id:17 gives the chapter holding page 17. (unit=toc only.)",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}| [match=words] Arabic words, ANDed; each may match in body or footnotes, e.g. {query:'الكلام'}. A word the library lacks in your spelling is searched in the spelling the books use and reported in `respelled_terms`: say so when you quote. [match=phrase] The words as a consecutive phrase, e.g. {query:'خيار المجلس'}. [match=near] The words within `distance` of each other, in any order. Phrase and near candidates come from an AND search and are verified in the full page text up to 1,500 pages or 12 s, so `total_verified` is not a library total; narrow `scope` when `candidate_cap_hit`. [match=exact] The exact string, typed WITH the diacritics / hamza form / digit system to enforce (it is not auto-diacritized) and matched as written; `preserve` decides which distinctions count. An AND search gathers at most 100 candidate pages and each is checked against the book's raw text; results keep candidate-relevance order. (match=words|phrase|near|exact only.) |
| scope | object | Restrict to books, authors, categories, a Hijri period or the other filters below; get ids from shamela_find(kind='category') or shamela_find(kind='name'). Strongly recommended on common words for match=phrase|near (verification stops after 1,500 candidate pages or 12 s) and match=exact (at most 100 candidate pages are verified): a narrow scope is what lets that window cover the topic. match=boolean: an unscoped search over a large library is exhaustive but slow, so scope narrows the question and speeds it up. (match=words|phrase|near|exact|boolean only.) |
| shape | string | How much of each hit to return. 'full' (default): every field, snippets included — ask for it when the answer will QUOTE the page. 'brief': book_id/page_id, printed_page, match_quality and matched_in_section, book metadata hoisted into a top-level `books` keyed by book_id, NO snippet — which pages, how well each matched and how to cite them, for a fraction of the characters, so far more rows survive the budget. 'index': book_id/page_id only, to choose what to read before paying to read it. Requires the 'shape.full_brief_index' capability (see shamela_get_brief). (match=words|phrase|near|batch only.) |
| all_of | array | The three lists are ONE Lucene BooleanQuery over the whole index: all_of MUST, any_of SHOULD (at least one), none_of MUST_NOT. AND — terms that must ALL appear on the page; a multi-word term is itself AND-searched (its words co-occur; not a phrase). Leave empty to rely on any_of, but not both: BAD_ARG. Results are ranked by relevance. E.g. {match:'boolean', all_of:['الوقف'], any_of:['المسجد','المقبرة'], none_of:['البيع'], scope:{category_ids:[17]}}. (match=boolean only.) |
| any_of | array | OR — at least ONE of these terms must appear on the page. Union of every term's hit set, then intersected with the all_of result. Leave empty to rely on all_of. (match=boolean only.) |
| offset | integer | Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (match=words|phrase|near|exact|boolean only.) |
| none_of | array | NOT — pages containing ANY of these terms are excluded, across the whole index (a MUST_NOT clause, not a subtraction inside a sampled window). Optional. (match=boolean only.) |
| options | object | Search options: morphology, wildcards, sort, search_in (body/foot), relax_when_empty. Defaults to body+foot, no toggles. preserve_* redirect to shamela_search(match='exact'). E.g. {query:'كلم', options:{morphology:true}}. (match=words only.) |
| queries | array | Several wordings of one question, run concurrently to assemble its evidence; results are merged, deduped by (book_id, page_id) and attributed to the probes that found each page (`probe_ids`): a page several probes found is corroboration across wordings, not a duplicate. Every probe's scope must carry book_ids, author_ids, category_ids or madhab, else the whole call is BAD_ARG. A probe that errors or outlasts deadline_ms is reported in its own slot and sets `incomplete`: a thin result is then not the library being silent. E.g. {queries:[{query:'الوتر واجب', scope:{category_ids:[14,19]}}, {query:'حكم صلاة الوتر', mode:'near', scope:{madhab:['hanafi']}}]}. (match=batch only.) |
| distance | integer | For match='near': maximum word span from the FIRST to the LAST query word, counted inclusively — 1 = adjacent, 2 allows one word between two query words. Ignored for match='phrase'. Suits fiqh terms that sit close but not adjacent: {match:'near', query:'بيع قبض', distance:5, scope:{category_ids:[17]}}. Default: 5. (match=phrase|near only.) |
| preserve | object | Which distinctions to enforce when each candidate is verified; at least one must be true (none = BAD_ARG), and every unset feature folds. E.g. {query:'أحمد', preserve:{preserve_hamza:true}}, {query:'عِلْم', preserve:{preserve_diacritics:true}}. (match=exact only.) |
| search_in | array | [match=phrase|near] Which page sections to verify the phrase in: body (matn), foot (footnotes). Default both; a hit's `matched_in_section` says where it was found. [match=boolean] Which page sections every clause (all_of, any_of and none_of alike) looks in: body (matn), foot (footnotes). Default ['body','foot']. (match=phrase|near|boolean only.) |
| deadline_ms | integer | Wall-clock budget for the whole batch. Probes still running when it expires are reported with status='timeout' and contribute nothing. A timeout is NOT a negative finding — it means the question was not fully asked. Default: 8000. (match=batch only.) |
| exclude_pages | array | Exact pages to keep out — the pages a previous round already returned. Excluding these rather than whole books is what lets a follow-up search find MORE evidence in a book that has already contributed some. (match=words|phrase|near only.) |
| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
| exclude_book_ids | array | Book ids to keep out of the results entirely. (match=words|phrase|near only.) |
| exclude_author_ids | array | Exclude every book by these authors. (match=words|phrase|near only.) |
| max_total_passages | integer | Hard cap on merged rows returned. Rows are ordered by match quality then probe agreement before the cut, so the cap drops the weakest evidence rather than an arbitrary tail. `truncated` says whether it fired. Default: 60. (match=batch only.) |
| exclude_category_ids | array | Exclude every book on these shelves. (match=words|phrase|near only.) |
| exclude_work_group_ids | array | Exclude every catalogue entry of these works — all printings at once. This is the one to use after a round returned «صحيح البخاري - ط السلطانية»: excluding that book_id alone leaves the other seven entries of group 1681 free to return the same text again as if it were a second source. (match=words|phrase|near only.) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return (1-100, default 20). (match=words|phrase|near|exact|boolean only.)"
},
"match": {
"enum": [
"words",
"phrase",
"near",
"exact",
"boolean",
"batch"
],
"type": "string",
"description": "Selects what the call does: words | phrase | near | exact | boolean | batch. Default words."
},
"query": {
"type": "string",
"minLength": 1,
"description": "[match=words] Arabic words, ANDed; each may match in body or footnotes, e.g. {query:'الكلام'}. A word the library lacks in your spelling is searched in the spelling the books use and reported in `respelled_terms`: say so when you quote. [match=phrase] The words as a consecutive phrase, e.g. {query:'خيار المجلس'}. [match=near] The words within `distance` of each other, in any order. Phrase and near candidates come from an AND search and are verified in the full page text up to 1,500 pages or 12 s, so `total_verified` is not a library total; narrow `scope` when `candidate_cap_hit`. [match=exact] The exact string, typed WITH the diacritics / hamza form / digit system to enforce (it is not auto-diacritized) and matched as written; `preserve` decides which distinctions count. An AND search gathers at most 100 candidate pages and each is checked against the book's raw text; results keep candidate-relevance order. (match=words|phrase|near|exact only.)"
},
"scope": {
"type": "object",
"properties": {
"madhab": {
"type": "array",
"items": {
"enum": [
"hanafi",
"maliki",
"shafii",
"hanbali"
],
"type": "string"
},
"description": "Restrict to books of these Sunni schools. master.db has NO madhab field, so this is resolved two ways: a book filed under a school-specific category (الفقه الحنفي/المالكي/الشافعي/الحنبلي) counts directly, and otherwise the MAIN AUTHOR's school is used, inferred from the categories that author's own books are filed under. That second path is what reaches مسائل فقهية and الفقه العام, where Shamela records no school — it raises madhab coverage of the fiqh shelves from 27% to 43%. Books whose school cannot be established are EXCLUDED by this filter, so do not read absence as 'no school said this'; for comparative questions leave madhab unset and scope by category instead."
},
"book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to these book IDs. Use `shamela_find(kind='name')` or `shamela_list_downloaded_books` to find IDs. Combine with other scope keys for intersection."
},
"book_type": {
"type": "array",
"items": {
"enum": [
"book",
"journal",
"manuscript",
"thesis",
"electronic",
"transcript"
],
"type": "string"
},
"description": "Restrict to these kinds of entry (master.db.book.book_type — the same filter row Shamela's own 'اختيار كتاب' window shows). 'transcript' (تفريغات) is a transcribed lecture series, not an authored book, and 'thesis'/'electronic' are likewise not printed works — excluding them sharpens a scholarly search. Of 8,594 entries, 7,334 are 'book'; 1,260 are not."
},
"period_to": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive upper bound. Pair with period_from."
},
"author_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books by these authors. Includes co-authored books. Use `shamela_find(kind='name', type='author')` to find IDs."
},
"period_from": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive lower bound. Matches book.book_date (composition year) OR author.death_number (death year). Pair with period_to."
},
"category_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books in these categories. Categories are flat in master.db (no parent_id, no transitive subtree expansion). Use `shamela_find(kind='category')` to find IDs."
},
"citable_only": {
"type": "boolean",
"description": "Keep only books whose page numbering matches a real printed edition (master.db.book.printed == 1 — Shamela's «يوافق المطبوع»). The other 1,417 entries are paginated by Shamela automatically, so their page numbers are NOT a citable reference to any published edition. Set this true whenever the answer will quote a page number as a citation. Default: false."
},
"downloaded_only": {
"type": "boolean",
"description": "Restrict to books actually downloaded on this user's machine (master.db.book.major_ondisk > 0). Critical for honest research scoping when using `shamela_search(match='words')` — only downloaded books have searchable content. Default: false."
}
},
"description": "Restrict to books, authors, categories, a Hijri period or the other filters below; get ids from shamela_find(kind='category') or shamela_find(kind='name'). Strongly recommended on common words for match=phrase|near (verification stops after 1,500 candidate pages or 12 s) and match=exact (at most 100 candidate pages are verified): a narrow scope is what lets that window cover the topic. match=boolean: an unscoped search over a large library is exhaustive but slow, so scope narrows the question and speeds it up. (match=words|phrase|near|exact|boolean only.)",
"additionalProperties": false
},
"shape": {
"enum": [
"full",
"brief",
"index"
],
"type": "string",
"description": "How much of each hit to return. 'full' (default): every field, snippets included — ask for it when the answer will QUOTE the page. 'brief': book_id/page_id, printed_page, match_quality and matched_in_section, book metadata hoisted into a top-level `books` keyed by book_id, NO snippet — which pages, how well each matched and how to cite them, for a fraction of the characters, so far more rows survive the budget. 'index': book_id/page_id only, to choose what to read before paying to read it. Requires the 'shape.full_brief_index' capability (see shamela_get_brief). (match=words|phrase|near|batch only.)"
},
"all_of": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "The three lists are ONE Lucene BooleanQuery over the whole index: all_of MUST, any_of SHOULD (at least one), none_of MUST_NOT. AND — terms that must ALL appear on the page; a multi-word term is itself AND-searched (its words co-occur; not a phrase). Leave empty to rely on any_of, but not both: BAD_ARG. Results are ranked by relevance. E.g. {match:'boolean', all_of:['الوقف'], any_of:['المسجد','المقبرة'], none_of:['البيع'], scope:{category_ids:[17]}}. (match=boolean only.)"
},
"any_of": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "OR — at least ONE of these terms must appear on the page. Union of every term's hit set, then intersected with the all_of result. Leave empty to rely on all_of. (match=boolean only.)"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of results to skip for pagination. Use with `limit` to page through large result sets. The response includes `has_more` and `next_offset` to drive paging. Default: 0. (match=words|phrase|near|exact|boolean only.)"
},
"none_of": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "NOT — pages containing ANY of these terms are excluded, across the whole index (a MUST_NOT clause, not a subtraction inside a sampled window). Optional. (match=boolean only.)"
},
"options": {
"type": "object",
"properties": {
"sort": {
"enum": [
"relevance",
"chronological"
],
"type": "string",
"description": "Result order. 'relevance' (default) ranks by how well the page matches — the right answer to 'find me X'. 'chronological' orders by the author's death year, then book, then page, so the EARLIEST sources come first — the right answer to 'who says this first' or 'how does this idea travel through the tradition'. Undated books sort last."
},
"search_in": {
"type": "array",
"items": {
"enum": [
"body",
"foot"
],
"type": "string"
},
"description": "Which page sections to search. 'body' = matn (المتن), 'foot' = footnotes (الحواشي). Default is both. Reader comments (التعليقات) are NOT searchable — Shamela keeps them in database/user/data.db, outside the Lucene index, so passing 'comment' returns OPTION_NOT_SUPPORTED rather than silently matching nothing. To search chapter titles use the separate `shamela_find(kind='heading')` tool."
},
"wildcards": {
"type": "boolean",
"description": "Interpret `*` (zero-or-more characters) and `?` (exactly-one character) within tokens. Examples: `صيا*` matches صيام/صيامهم, `ص?م` matches صام/صوم/صمم. Leading wildcards (`*ابن`) are slow. Cannot combine with `morphology`. With this OFF, `*` and `?` are treated as ordinary punctuation and split the word, so a stray one no longer zeroes the search. CAVEAT on prefixes: the index folds some words as a WHOLE — «مائة» is stored as «ميه», «داوود» as «داود» — and a wildcard stem is folded without the letters the wildcard replaced, so `مائ*` becomes `ماي*` and reaches مائع/مائدة but NOT مائة. When a prefix search returns less than you expect for a word like these, search the full word without a wildcard instead. Default: false."
},
"morphology": {
"type": "boolean",
"description": "Search Arabic root forms via the AlKhalil morphological analyzer. Useful when looking for all word forms (يكتب، كاتب، مكتوب…) of a root (كتب). Cannot be combined with `wildcards`. Default: false."
},
"preserve_hamza": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here — the index folds ٱآأإ→ا before storing. Use `shamela_search(match='exact', {preserve:{preserve_hamza:true}})` to distinguish «أحمد» from «احمد». Default: false."
},
"preserve_digits": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here — the index unifies Arabic-Indic and Western digits. Use `shamela_search(match='exact', {preserve:{preserve_digits:true}})` to distinguish ٢٥٥ from 255. Default: false."
},
"relax_when_empty": {
"type": "boolean",
"description": "When the AND of every term matches no page, retry requiring only the largest number of your terms that some page does carry, and report it in `relaxed_min_match`. Only ever fires on a result that would otherwise be empty, and never drops below half your terms. Set false to keep a strict all-terms-or-nothing search. Default: true."
},
"preserve_diacritics": {
"type": "boolean",
"description": "Returns OPTION_NOT_SUPPORTED here — the index itself stores no diacritics, so this search cannot honor them. Use `shamela_search(match='exact', {preserve:{preserve_diacritics:true}})`, which re-checks each candidate against the book's raw text. Default: false."
}
},
"description": "Search options: morphology, wildcards, sort, search_in (body/foot), relax_when_empty. Defaults to body+foot, no toggles. preserve_* redirect to shamela_search(match='exact'). E.g. {query:'كلم', options:{morphology:true}}. (match=words only.)",
"additionalProperties": false
},
"queries": {
"type": "array",
"items": {
"type": "object",
"required": [
"query",
"scope"
],
"properties": {
"id": {
"type": "string",
"maxLength": 32,
"minLength": 1,
"description": "Your label for this probe, echoed back on every row it found (`probe_ids`). Defaults to the probe's index, e.g. 'p0'."
},
"mode": {
"enum": [
"and",
"phrase",
"near"
],
"type": "string",
"description": "'and' (default) = the regular all-terms page search. 'phrase' = the words as a CONSECUTIVE phrase — use it when the caller is holding a quotation. 'near' = within `distance` words, any order."
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Rows this probe may contribute before dedupe; `max_total_passages` then caps the merged total. Default: 10."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Arabic search text. In mode='and' every word is required (each may match body or footnotes); in mode='phrase' the words must be consecutive; in mode='near' within `distance` words in any order."
},
"scope": {
"type": "object",
"properties": {
"madhab": {
"$ref": "#/properties/scope/properties/madhab"
},
"book_ids": {
"$ref": "#/properties/scope/properties/book_ids"
},
"book_type": {
"$ref": "#/properties/scope/properties/book_type"
},
"period_to": {
"$ref": "#/properties/scope/properties/period_to"
},
"author_ids": {
"$ref": "#/properties/scope/properties/author_ids"
},
"period_from": {
"$ref": "#/properties/scope/properties/period_from"
},
"category_ids": {
"$ref": "#/properties/scope/properties/category_ids"
},
"citable_only": {
"$ref": "#/properties/scope/properties/citable_only"
},
"downloaded_only": {
"$ref": "#/properties/scope/properties/downloaded_only"
}
},
"description": "REQUIRED. Must carry at least one of book_ids / author_ids / category_ids / madhab. An unscoped probe is rejected: term-frequency ranking over all 8,594 books returns whichever book repeats the word most («التيمم» puts a poetry anthology ahead of the fiqh manuals), which is not the question being asked.",
"additionalProperties": false
},
"distance": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "For mode='near' only: maximum word span from the FIRST to the LAST query word, inclusive (1 = adjacent). Ignored for 'and' and 'phrase'. Default: 5."
},
"exclude_pages": {
"$ref": "#/properties/exclude_pages",
"description": "Exact pages to keep out — the pages a previous round already returned. Excluding these rather than whole books is what lets a follow-up search find MORE evidence in a book that has already contributed some."
},
"exclude_book_ids": {
"$ref": "#/properties/exclude_book_ids",
"description": "Book ids to keep out of the results entirely."
},
"exclude_author_ids": {
"$ref": "#/properties/exclude_author_ids",
"description": "Exclude every book by these authors."
},
"exclude_category_ids": {
"$ref": "#/properties/exclude_category_ids",
"description": "Exclude every book on these shelves."
},
"exclude_work_group_ids": {
"$ref": "#/properties/exclude_work_group_ids",
"description": "Exclude every catalogue entry of these works — all printings at once. This is the one to use after a round returned «صحيح البخاري - ط السلطانية»: excluding that book_id alone leaves the other seven entries of group 1681 free to return the same text again as if it were a second source."
}
},
"additionalProperties": false
},
"maxItems": 24,
"minItems": 1,
"description": "Several wordings of one question, run concurrently to assemble its evidence; results are merged, deduped by (book_id, page_id) and attributed to the probes that found each page (`probe_ids`): a page several probes found is corroboration across wordings, not a duplicate. Every probe's scope must carry book_ids, author_ids, category_ids or madhab, else the whole call is BAD_ARG. A probe that errors or outlasts deadline_ms is reported in its own slot and sets `incomplete`: a thin result is then not the library being silent. E.g. {queries:[{query:'الوتر واجب', scope:{category_ids:[14,19]}}, {query:'حكم صلاة الوتر', mode:'near', scope:{madhab:['hanafi']}}]}. (match=batch only.)"
},
"distance": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "For match='near': maximum word span from the FIRST to the LAST query word, counted inclusively — 1 = adjacent, 2 allows one word between two query words. Ignored for match='phrase'. Suits fiqh terms that sit close but not adjacent: {match:'near', query:'بيع قبض', distance:5, scope:{category_ids:[17]}}. Default: 5. (match=phrase|near only.)"
},
"preserve": {
"type": "object",
"properties": {
"preserve_hamza": {
"type": "boolean",
"description": "Enforce hamza/alef forms exactly: «أحمد» will not match «احمد»; ٱآأإ, ؤ, ئ, ء, ى, ة are all kept distinct. Default: false."
},
"preserve_digits": {
"type": "boolean",
"description": "Distinguish digit systems: Arabic-Indic «٢٥٥» will not match Western «255» (and vice-versa). Default: false."
},
"preserve_diacritics": {
"type": "boolean",
"description": "Enforce التشكيل exactly: «عِلْم» will not match «عَلَم». The query's own diacritics are honored verbatim. Default: false."
}
},
"description": "Which distinctions to enforce when each candidate is verified; at least one must be true (none = BAD_ARG), and every unset feature folds. E.g. {query:'أحمد', preserve:{preserve_hamza:true}}, {query:'عِلْم', preserve:{preserve_diacritics:true}}. (match=exact only.)",
"additionalProperties": false
},
"search_in": {
"type": "array",
"items": {
"enum": [
"body",
"foot"
],
"type": "string"
},
"description": "[match=phrase|near] Which page sections to verify the phrase in: body (matn), foot (footnotes). Default both; a hit's `matched_in_section` says where it was found. [match=boolean] Which page sections every clause (all_of, any_of and none_of alike) looks in: body (matn), foot (footnotes). Default ['body','foot']. (match=phrase|near|boolean only.)"
},
"deadline_ms": {
"type": "integer",
"maximum": 60000,
"minimum": 1,
"description": "Wall-clock budget for the whole batch. Probes still running when it expires are reported with status='timeout' and contribute nothing. A timeout is NOT a negative finding — it means the question was not fully asked. Default: 8000. (match=batch only.)"
},
"exclude_pages": {
"type": "array",
"items": {
"type": "object",
"required": [
"book_id",
"page_id"
],
"properties": {
"book_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"page_id": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"description": "Exact pages to keep out — the pages a previous round already returned. Excluding these rather than whole books is what lets a follow-up search find MORE evidence in a book that has already contributed some. (match=words|phrase|near only.)"
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
},
"exclude_book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Book ids to keep out of the results entirely. (match=words|phrase|near only.)"
},
"exclude_author_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Exclude every book by these authors. (match=words|phrase|near only.)"
},
"max_total_passages": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Hard cap on merged rows returned. Rows are ordered by match quality then probe agreement before the cut, so the cap drops the weakest evidence rather than an arbitrary tail. `truncated` says whether it fired. Default: 60. (match=batch only.)"
},
"exclude_category_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Exclude every book on these shelves. (match=words|phrase|near only.)"
},
"exclude_work_group_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Exclude every catalogue entry of these works — all printings at once. This is the one to use after a round returned «صحيح البخاري - ط السلطانية»: excluding that book_id alone leaves the other seven entries of group 1681 free to return the same text again as if it were a second source. (match=words|phrase|near only.)"
}
},
"additionalProperties": false
}{
"type": "object",
"required": [
"query",
"scope"
],
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 10,
"minimum": 1,
"description": "Maximum passages to return (max 10)."
},
"query": {
"type": "string",
"description": "Arabic search text. A quoted wording works best; a topic also works."
},
"scope": {
"enum": [
"hadith-primary",
"tafsir-canonical",
"fiqh-hanafi",
"fiqh-maliki",
"fiqh-shafii",
"fiqh-hanbali",
"fiqh-comparative",
"aqeedah",
"hadith-sciences",
"tafsir",
"seerah",
"lugha"
],
"type": "string",
"description": "hadith-primary — The eight primary hadith collections, edition-pinned; tafsir-canonical — Canonical tafsir — Ibn Kathir, al-Tabari, Ibn al-Jawzi first; fiqh-hanafi — Hanafi fiqh (+ usul, comparative); fiqh-maliki — Maliki fiqh (+ usul, comparative); fiqh-shafii — Shafi'i fiqh (+ usul, comparative); fiqh-hanbali — Hanbali fiqh (+ usul, comparative); fiqh-comparative — All four schools plus comparative and fatwa collections; aqeedah — Creed and sects; hadith-sciences — Hadith commentary, takhrij and the sciences of hadith; tafsir — The whole tafsir shelf and Quranic sciences; seerah — Prophetic biography, history and biographical dictionaries; lugha — Arabic language, lexicons, grammar and adab"
}
},
"additionalProperties": false
}| response_format | string | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"term"
],
"properties": {
"mode": {
"enum": [
"literal",
"morphological"
],
"type": "string",
"default": "literal",
"description": "'literal' counts pages carrying the WORD as written (plus the ordinary spelling folds). 'morphological' expands it to every AlKhalil root reading and counts those — which is far broader than most callers expect: «الاستصناع» reports 393,498 pages across 7,405 books morphologically against 1,510 literally, an answer that says every shelf holds the topic. Use 'literal' to size a topic before planning retrieval; use 'morphological' to trace a ROOT through its derivations."
},
"term": {
"type": "string",
"minLength": 1,
"description": "Arabic word or root to profile (e.g. «الاستصناع»، «صبر»، «رحم»). Under mode='literal' (default) only the word as written is counted; under mode='morphological' it is matched via the AlKhalil analyzer, so all derived forms (صابر، يصبر، اصطبار…) are counted, not just the literal string."
},
"scope": {
"type": "object",
"properties": {
"madhab": {
"type": "array",
"items": {
"enum": [
"hanafi",
"maliki",
"shafii",
"hanbali"
],
"type": "string"
},
"description": "Restrict to books of these Sunni schools. master.db has NO madhab field, so this is resolved two ways: a book filed under a school-specific category (الفقه الحنفي/المالكي/الشافعي/الحنبلي) counts directly, and otherwise the MAIN AUTHOR's school is used, inferred from the categories that author's own books are filed under. That second path is what reaches مسائل فقهية and الفقه العام, where Shamela records no school — it raises madhab coverage of the fiqh shelves from 27% to 43%. Books whose school cannot be established are EXCLUDED by this filter, so do not read absence as 'no school said this'; for comparative questions leave madhab unset and scope by category instead."
},
"book_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to these book IDs. Use `shamela_find(kind='name')` or `shamela_list_downloaded_books` to find IDs. Combine with other scope keys for intersection."
},
"book_type": {
"type": "array",
"items": {
"enum": [
"book",
"journal",
"manuscript",
"thesis",
"electronic",
"transcript"
],
"type": "string"
},
"description": "Restrict to these kinds of entry (master.db.book.book_type — the same filter row Shamela's own 'اختيار كتاب' window shows). 'transcript' (تفريغات) is a transcribed lecture series, not an authored book, and 'thesis'/'electronic' are likewise not printed works — excluding them sharpens a scholarly search. Of 8,594 entries, 7,334 are 'book'; 1,260 are not."
},
"period_to": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive upper bound. Pair with period_from."
},
"author_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books by these authors. Includes co-authored books. Use `shamela_find(kind='name', type='author')` to find IDs."
},
"period_from": {
"type": "integer",
"maximum": 2000,
"minimum": 1,
"description": "Hijri year, inclusive lower bound. Matches book.book_date (composition year) OR author.death_number (death year). Pair with period_to."
},
"category_ids": {
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0
},
"description": "Restrict to books in these categories. Categories are flat in master.db (no parent_id, no transitive subtree expansion). Use `shamela_find(kind='category')` to find IDs."
},
"citable_only": {
"type": "boolean",
"default": false,
"description": "Keep only books whose page numbering matches a real printed edition (master.db.book.printed == 1 — Shamela's «يوافق المطبوع»). The other 1,417 entries are paginated by Shamela automatically, so their page numbers are NOT a citable reference to any published edition. Set this true whenever the answer will quote a page number as a citation."
},
"downloaded_only": {
"type": "boolean",
"default": false,
"description": "Restrict to books actually downloaded on this user's machine (master.db.book.major_ondisk > 0). Critical for honest research scoping when using `shamela_search(match='words')` — only downloaded books have searchable content."
}
},
"description": "Restrict the profile to specific books, authors, categories, or a Hijri date range. Use shamela_find(kind='category') / shamela_find(kind='name') to find IDs. Omit to profile the whole library installed on this server.",
"additionalProperties": false
},
"response_format": {
"enum": [
"markdown",
"json",
"none"
],
"type": "string",
"default": "markdown",
"description": "Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief)."
}
},
"additionalProperties": false
}