Tadabbur video API

Short videos of reflection (tadabbur) on the ayahs of the Quran, by surah, mushaf page or ayah, from the app «مصحف التدبر» (quran-tadabbur.com). The API is static JSON: no key, read-only, CORS for every origin.

Endpoints

/v1/ayahs/{surah}/{ayah}.json

An ayah: its videos, best first. Example: /v1/ayahs/2/255.json

/v1/pages/{page}.json

A mushaf page (1-604): the videos touching it, by ayah. Example: /v1/pages/42.json

/v1/surahs/{surah}.json

A surah: all its videos in mushaf order, by ayah. Example: /v1/surahs/2.json

/v1/surahs.json

The 114 surahs with their video counts and coverage.

/v1/index.json

URL templates, counts, coverage, series and attribution.

/v1/schema.json

The JSON Schema of every document.

/v1/build.json

The identity of this deployment (SHA-256 of every other file).

Numbers have no leading zeros. Every ayah, page and surah has a document (with an empty videos list when it has none); any other path answers 404 with a JSON error.

Example

curl -s https://api.quran-tadabbur.com/v1/ayahs/2/255.json

The same documents are served at https://quran-tadabur-api.pages.dev.

Each video has:

kind

clip: cut for these ayahs; episode: the whole episode, for ayahs whose own clip is not aligned yet; intro: the part of an episode before its first ayah.

surah, ayahFrom, ayahTo

The ayah range. Several ayahs can share one explanation, and a long one is split into parts.

video.url

The hosted MP4 (portrait 540x960), or null.

poster.url

The hosted poster, or the YouTube thumbnail.

youtube

The same segment in the source video: startMs/endMs in source time, and an embedUrl bounded with start/end.

cues

The offsets (in the video) where the discussion moves on to a later ayah.

review.decision

auto: the boundaries were found automatically and published without a manual review.

The videos of an ayah are ranked: clips cut for the ayah first, then whole episodes (ayahs not aligned yet), then intros; ties keep mushaf order. The videos of a page or surah are in mushaf order.

Caching and versions

Responses carry Cache-Control: public, max-age=300, stale-while-revalidate=3600 and an ETag: send If-None-Match to get 304 Not Modified. /v1/build.json changes whenever any document changes. Breaking changes would come as /v2/, next to /v1/.

Videos and posters are served from Cloudflare R2's public r2.dev URL, which Cloudflare rate-limits and does not intend for production traffic; a custom media domain can replace it. Published videos are never replaced: a new cut of a clip gets a new URL.

Attribution

«مقاطع حظر التجول» by Dr. Fadel Soliman, published by Bridges Foundation on YouTube. The cut clips are hosted with Bridges Foundation's permission. Playlist: https://www.youtube.com/playlist?list=PLukAHj56HNKbebRe2Wfy_wIZ9RySsJ8fo. Surah names, ayah pages and juz: the Madani mushaf (Hafs) of the King Fahd Glorious Qur'an Printing Complex, through the Quran.com / Quran Foundation API.