Hosted API access is disabled on `al-quran-database.vercel.app` for now. Use the repository locally or self-host this project to run the API endpoints documented here.

API Reference

Stable contracts live under `/api/v1/*`, with legacy `/api/*` aliases retained for compatibility. The official hosted domain keeps these endpoints private for now, so use them from a local or self-hosted deployment.

REST Envelope

{
  "success": true,
  "data": {},
  "meta": {}
}

Headers

REST and GraphQL responses include `X-API-Version`, `X-API-Latest-Version`, and cache status headers from `X-Cache`.

Search Rule

`/search` and GraphQL `search` accept `edition` or `language`. Sending both returns a validation error.

GraphQL

POST preferred/api/v1/graphql

`POST` is recommended for app traffic. `GET` with `query` and optional `variables` query params also works for debugging and cached reads in your own deployment.

Query

query GetAyah($id: Int!) {
  ayah(id: $id, includeWords: true) {
    text
    translation
    words {
      text
      root
    }
    knowledge {
      themes
      historical_context
    }
  }
}

Root Fields

surahs(page, limit)surah(id, edition)ayah(id, edition, includeWords)juz(id, edition)hizb(id, edition)rub(id, edition)mushafPage(id, edition)search(query, edition, language, page, limit)knowledge(ayahId)faqsresearchReferencesmeta

REST v1 Endpoints

GET/api/v1/surahs?page=1&limit=10

List surahs with pagination metadata. Stable list endpoint for SDKs, docs previews, and browse UIs.

{
  "success": true,
  "data": [{ "id": 1, "name_en": "Al-Faatiha" }],
  "meta": { "total": 114, "page": 1, "limit": 10, "total_pages": 12 }
}

GET/api/v1/surahs/1?edition=en.sahih

Resolve one surah with hydrated ayahs and optional edition translation data.

{
  "success": true,
  "data": {
    "id": 1,
    "ayahs": [{ "id": 1, "translation": "In the name of Allah..." }]
  }
}

GET/api/v1/ayahs/1?edition=en.sahih&include_words=true

Resolve one absolute ayah ID with optional translation, word breakdown, and knowledge payload.

{
  "success": true,
  "data": {
    "id": 1,
    "text": "بِسْمِ اللَّهِ...",
    "words": [{ "text": "بِسْمِ", "position": 1 }]
  }
}

GET/api/v1/search?q=mercy&language=en&limit=5

Ranked full-text search. Use either edition or language filter, never both in same request.

{
  "success": true,
  "data": [{ "id": 43, "matched_identifiers": ["translation"] }],
  "meta": { "total": 5, "page": 1, "limit": 5, "language": "en" }
}

GET/api/v1/juz/1?edition=en.sahih

Resolve one juz with range metadata and included ayahs.

GET/api/v1/hizb/1?edition=en.sahih

Resolve one hizb with range metadata and included ayahs.

GET/api/v1/rub/1?edition=en.sahih

Resolve one rub with range metadata and included ayahs.

GET/api/v1/pages/1?edition=en.sahih

Resolve one Mushaf page with ayah range and included ayahs.

GET/api/v1/words?ayah_id=1

Fetch word-by-word tokens, roots, and morphology for one absolute ayah.

{
  "success": true,
  "data": [{ "ayah_id": 1, "text": "بِسْمِ", "root": null }],
  "meta": { "count": 4 }
}

GET/api/v1/duas?page=1&limit=10

List extracted duas with pagination metadata.

GET/api/v1/reciters

List normalized reciter metadata and identifiers.

GET/api/v1/faqs

Return FAQ entries curated in knowledge-base source.

GET/api/v1/knowledge/255

Return one ayah knowledge entry including themes, context, cross references, and notes.

GET/api/v1/meta

Return dataset provenance, row counts, and knowledge coverage counters.

{
  "success": true,
  "data": {
    "dataset": { "counts": { "ayahs": 6236 } },
    "knowledge": { "ayah_entries": 6236 }
  }
}