# Tabseer Al-Hadith

Tabseer provides Arabic and English Hadith texts, narrator biographies, scholarly appraisals, and transmission-chain views across 17 collections.

## Machine-readable access

- [OpenAPI contract](/openapi.json): public GET operations, parameters, limits, and response envelopes.
- [Collections and chapter titles](/api/collections): discover supported collection IDs and exact chapter titles.
- [Hadith example](/api/hadith/bukhari/1): one record in a {status, message, data} envelope.
- [Search example](/api/search?q=intentions&limit=20): {data: [...]} results; optional collection and narrator filters.
- [Narrator directory](/api/narrators?page=1&limit=24): paginated profiles at data.narrators and data.pagination.
- [Human-readable sitemap](/sitemap.xml): collection and chapter pages.

## Retrieval and citation

Use public JSON GET routes without authentication or JavaScript. All API paths are relative to this site's origin. Use chapter pagination with lastHadithNumber set to the final record's hadith_number; stop when fewer than limit records arrive or a chapter request returns 404. Do not assume every integer in a collection's advertised count exists.

Cite the human page /hadith/{collection}/{number} or /narrator/{id}, retaining book_name, hadith_number, original Arabic text, and any supplied source attribution. Preserve differing scholarly appraisals. Missing biography, grade, or source fields mean unavailable data, not verified facts. A transmission-tree similarity link is not an independent authenticity judgment.

## Request etiquette

Honor Cache-Control and reuse responses. Prefer exact record retrieval or chapter cursors over deep search pagination. Search text is limited to 200 characters; limits and pagination ceilings are in OpenAPI. Use modest concurrency (up to four requests at once), exponential backoff for 429/5xx responses, and Retry-After when present. Errors are not cacheable. Public CDN responses may lag edits by their stated freshness and stale-while-revalidate windows.

Admin, login, bookmarks, and write operations are outside this public interface. Do not use them for crawling.