# Thaqalayn

> A library for studying Shia Islamic sources, including the Quran, hadith, duas, and narrator information.

Content pages identify their sources and available translations. Preserve source wording and distinguish translations, commentary, and hadith gradings when citing them.

Use https://thaqalayn.com for canonical reading URLs and https://api.thaqalayn.com for the JSON endpoints below. Discover current reading pages through the sitemap index, including its commentary shards.

## Library

- [Hadith library](https://thaqalayn.com/): Browse hadith collections.
- [Quran](https://thaqalayn.com/quran): Browse surahs, translations, and commentary.
- [Duas](https://thaqalayn.com/duas): Browse supplications and ziyarat.
- [Search](https://thaqalayn.com/search): Search the library.
- [Arabic library](https://thaqalayn.com/ar): Browse the Arabic interface.

## Access and discovery

- [API catalog](https://thaqalayn.com/.well-known/api-catalog): Machine-readable links to public JSON endpoints and this access guide.
- [OpenAPI specification](https://thaqalayn.com/openapi.json): Public API paths, parameters, response schemas, languages, and error behavior. No authentication is required for the documented operations.
- [Sitemap index](https://thaqalayn.com/sitemap-index.xml): Discover indexable content pages.
- [Crawler policy](https://thaqalayn.com/robots.txt): Crawl directives.
- [About Thaqalayn](https://thaqalayn.com/about): Project information.

## Reading pages as Markdown

Send `Accept: text/markdown` to a reading-page URL to receive Markdown. Send `Accept: text/html` for the browser page. Cite the canonical reading URL for either format.

Example: `curl -H 'Accept: text/markdown' https://thaqalayn.com/hadith/2/1/1/1`

## Public JSON API

These endpoints and the translation manifests below support anonymous GET and HEAD requests from any origin, with OPTIONS preflight support. For browser requests, use `credentials: "omit"`; no API key is needed.

The documented GET operations have no pagination or language query parameters. The hadith lookup selects English (`text_en`) and Arabic (`text_ar`); either field can be null. Static book exports use per-record `language` labels and `content` fields. Book-export IDs are not interchangeable with reading-page URL pointers. A missing export returns HTTP 404 with plain text; a missing hadith returns HTTP 200 with null content. Check status and Content-Type before parsing errors, which can be plain text or JSON.

- [Hadith book index](https://api.thaqalayn.com/books): Legacy book-export catalog. Use the sitemap for the current website inventory.
- [Example book export](https://api.thaqalayn.com/book/1): Static JSON export; replace `1` with an export ID from the book index.
- [Example hadith lookup](https://api.thaqalayn.com/hadith/2/1/1/1): A single hadith with available Arabic and English text. The four path values are the book URL pointer, section number, chapter number, and hadith number, matching the reading-page path. The response contains `data.hadith`, `data.chapter`, `fromCache`, and `cachedAt`. Check that `data.hadith` is non-null; HTTP 200 alone does not establish that a record exists.

Example: `curl https://api.thaqalayn.com/hadith/2/1/1/1`

## Translation manifests

The manifests are public JSON metadata. The download endpoints they describe currently require mobile access credentials; they are not anonymous bulk downloads.

Read `language` (Quran and dua) or `code` (word-by-word) from the current manifest for available package languages. The word-by-word manifest excludes bundled English. `sizeBytes` is an estimate; `checksum` is a metadata fingerprint, not a hash of downloaded file bytes.

- [Quran translation manifest](https://api.thaqalayn.com/api/translations/manifest): Available Quran translation packages.
- [Dua translation manifest](https://api.thaqalayn.com/api/dua-translations/manifest): Available dua translation packages.
- [Quran word-by-word manifest](https://api.thaqalayn.com/api/wbw/manifest): Available word-by-word packages.