KitabGrid Developer APIAPI v1 documentation
REST API · v1

Quran, Hadith, translations and approved audio

The external API is intentionally stricter than the public website: only content that is both publication-approved and source/reuse-approved is eligible to leave KitabGrid.

Base URLhttps://kitabgrid.com/api/v1
FormatJSON · UTF-8
AuthenticationBearer / X-KitabGrid-Key

1. Access flow

  1. Submit the domain/subdomain, contact details, intended use, requested data scopes and translation languages.
  2. Verify the compulsory email address.
  3. KitabGrid manually reviews the website, requested scopes and licensing implications.
  4. After approval, a short-lived one-time claim link generates the credential. The raw key is not stored or emailed.

2. Authentication and key types

kg_live_… — server secret. Keep it backend-only. A request carrying this key is rejected when an Origin header indicates browser use.

kg_pub_… — browser credential. It is usable only from the exact approved HTTPS origin and is not treated as a private secret.

curl -H "Authorization: Bearer kg_live_REPLACE_ME" \ "https://kitabgrid.com/api/v1/quran/ayahs/1/1?lang=en&include=translations,audio"
fetch("https://kitabgrid.com/api/v1/quran/ayahs/1/1?lang=pl&include=translations", { headers: { "X-KitabGrid-Key": "kg_pub_REPLACE_ME" } }).then(r => r.json()).then(console.log);

Do not use query-string API keys. Keys belong in an HTTP header so they are less likely to leak through URLs, referrers or logs.

3. API endpoints

MethodEndpointScopePurpose
GET/clientauthenticatedCurrent client, domain, scopes and quota.
GET/languagesauthenticatedLanguages granted to the client and available publicly.
GET/quran/surahsquran.read114-Surah catalogue where approved data exists.
GET/quran/surahs/{surah}quran.readSurah metadata.
GET/quran/surahs/{surah}/ayahsquran.readPaginated ayahs; translations/audio can be included.
GET/quran/ayahs/{surah}/{ayah}quran.readSingle ayah with optional translations/audio.
GET/quran/recitersquran.audio.readApproved reciters with reusable audio sources.
GET/hadith/search?q=...hadith.readSearch approved published Hadith records.
GET/hadith/collectionshadith.readPublished/partial approved collections.
GET/hadith/collections/{slug}hadith.readCollection metadata.
GET/hadith/collections/{slug}/hadithshadith.readPaginated approved Hadith records.
GET/hadith/collections/{slug}/hadiths/{number}hadith.readSingle Hadith with optional approved translations/audio.

4. Common parameters

lang=en,pl
Comma-separated granted translation languages, maximum 5.
include=translations,audio
Adds only the requested optional blocks and only when the matching scope is granted.
reciter={id}
Selects a specific approved Quran reciter. If unavailable, another reciter is not silently substituted.
page / per_page
Pagination. per_page is capped at 50.

5. Content, source and licence rules

  • Quran/Hadith source text is returned only through approved source records.
  • Translations must be approved; Hadith translations also respect a published translation-version gate where that workflow exists.
  • Audio is returned only when the audio source itself is approved for reuse. Hadith audio support exists, but returns no audio until approved narration records are actually stored.
  • Source blocks can include title, author/translator, publisher, edition, source URL, licence name/URL and reuse scope. Integrators must preserve required attribution and source-specific licence notices.
{ "data": { "surah": 1, "ayah": 1, "arabic": "…", "translations": [{ "language": "pl", "text": "…", "source": {"title": "…", "license_name": "…", "reuse_scope": "…"} }], "audio": {"available": true, "items": [{"reciter": "…", "url": "…", "source": {"title": "…"}}]} }, "meta": {"version": "v1", "request_id": "…"} }

6. Rate limits, CORS and errors

The default approval profile is 60 requests/minute and 10,000/day, but administrators can assign a different limit per client. A 429 response means the current limit was exceeded.

Browser credentials receive an exact Access-Control-Allow-Origin only for the approved domain/subdomain. Wildcard CORS is not used for authenticated browser access.

HTTPMeaning
400Invalid parameter or malformed request.
401Missing/invalid/revoked credential.
403Scope, language, origin or client state does not allow the request.
404No eligible approved public record exists.
429Rate or daily quota exceeded.
503Required API storage/data dependency is unavailable.