DOCSEARCHbyAlgolia
Submit Docs

Quran Foundation API Documentation

website·Indexed 40 days ago

https://api-docs.quran.com/

Developer resources for the Quran Foundation, featuring OpenAPI specifications for Content (v4), Search (v1), Analytics, and User-related APIs. Includes OAuth2 and OpenID Connect integration guides, as well as SDK integration prompts for JavaScript and Python.

Tokens
141.7K
Snippets
709
Records
963
Agent score
57%

What's inside Quran Foundation

  1. Retrieve recitation information

    v4.json

    Get detailed information about a specific ayah-by-ayah recitation using the /resources/recitations/{recitation_id}/info endpoint. Note that you must use the recitation ID from the recitations resource, not the chapter-reciter IDs.

    Request Details:

    • Method: GET
    • Base URL: https://apis.quran.foundation/content/api/v4
    • Path: /resources/recitations/{recitation_id}/info
    • Required Headers:
      • x-auth-token: Your access token
      • x-client-id: Your client ID

    Error Handling Guidance:

    • 401 Unauthorized: Token expired. Re-request the token and retry once.
    • 403 Forbidden: Access denied. Verify client credentials.
    • 429 Too Many Requests: Rate limited. Implement exponential backoff.

  2. PostSerialized schema for Quran Reflect posts

    v4.json
    The PostSerialized schema defines the structure of a post within the Quran Reflect system. It includes metadata about the author, content, visibility, and moderation status.
    {
  "id": "number",
  "authorId": "string",
  "body": "string",
  "discussionId": "number",
  "draft": "boolean (default: false)",
  "createdAt": "string (date-time)",
  "updatedAt": "string (date-time)",
  "publishedAt": "string (date-time)",
  "global": "boolean",
  "toxicityScore": "number",
  "reported": "boolean (default: false)",
  "views": "number",
  "removed": "boolean (default: false)",
  "verified": "boolean (default: false)",
  "roomPostStatus": "number (0: OnlyMembers, 1: Publicly, 2: AsRoom)",
  "hidden": "boolean (default: false)",
  "commentsCount": "number (default: 0)",
  "likesCount": "number (default: 0)",
  "viewsCount": "number (default: 0)",
  "languageId": "number",
  "languageName": "string",
  "moderationStatus": "number (1: featured, 2: promoted, 3: normal, 4: hidden, 5: private_note, 6: requested_review, 30: deleted)",
  "reviewedAt": "string (date-time)",
  "featuredAt": "string (date-time)",
  "estimatedReadingTime": "number (default: 0)",
  "roomId": "number",
  "postTypeId": "number (1 = Reflection, 2 = Lesson)",
  "postTypeName": "string (e.g., 'reflection' or 'lesson')"
}

  3. AnswersQuestionDto schema definition

    v4.json
    The AnswersQuestionDto represents a question about the Quran. It includes the question body, its type (CLARIFICATION, TAFSIR, or COMMUNITY), associated verse ranges, and a list of answers.
    {
  "id": "string",
  "body": "string",
  "type": "CLARIFICATION | TAFSIR | COMMUNITY",
  "ranges": ["2:255-2:257"],
  "surah": 2,
  "theme": ["string"],
  "summary": "string",
  "references": ["string"],
  "language": "en",
  "status": "New | Draft | Published | Answered",
  "answers": []
}

  4. Understand the Chapter Reciters model

    v4.json
    The chapter-reciters object contains details about a reciter, including their English name, recitation style, and qirat. Both style and qirat include a language_name for localization.
    {
  "id": 3,
  "name": "Abu Bakr al-Shatri",
  "style": {
    "name": "Murattal",
    "language_name": "english"
  },
  "qirat": {
    "name": "Hafs",
    "language_name": "english"
  },
  "translated_name": {
    "name": "Abu Bakr al-Shatri",
    "language_name": "english"
  }
}

  5. Understand the Chapter data model

    v4.json
    The Chapter object provides metadata about a Surah, including its revelation place (e.g., Makkah), revelation order, whether it starts with Bismillah, the total verse count, and the page range it covers in the Mushaf.
    {
  "id": 1,
  "revelation_place": "makkah",
  "revelation_order": 5,
  "bismillah_pre": false,
  "name_complex": "Al-Fātiĥah",
  "name_arabic": "الفاتحة",
  "verses_count": 7,
  "pages": [1, 1],
  "translated_name": {
    "language_name": "english",
    "name": "The Opener"
  },
  "name_simple": "Al-Fatihah"
}

  7. Get information for a specific Tafsir

    v4.json
    Retrieve detailed information about a specific Tafsir, such as author details and publication date, using the /resources/tafsirs/{tafsir_id}/info endpoint. The response contains an info object with the Tafsir's id and a description in Markdown or HTML format.
    // Example Successful Response (200 OK)
{
  "info": {
    "id": 169,
    "info": "<p>Tafsir Ibn Kathir is one of the most comprehensive classical commentaries...</p>"
  }
}

  8. Understand the OpenID Connect Userinfo schema

    v1.json

    The oidcUserInfo object provides profile information about the end-user. It contains the following properties:

    • email: The user's preferred email address (RFC 5322 compliant). Note: This value should not be relied upon as a unique identifier.
    • first_name: The given name(s) of the user.
    • last_name: The surname(s) or family name(s) of the user.

  9. Retrieve Uthmani Tajweed script of ayahs

    v4.json
    Use the /quran/verses/uthmani_tajweed endpoint to get color-coded Uthmani tajweed text. Tajweed rules are embedded directly in the text using <tajweed> HTML tags. The response includes an array of verses and metadata about the applied filters.
    // Example Response
{
  "verses": [
    {
      "id": 1,
      "verse_key": "1:1",
      "text_uthmani_tajweed": "بِسْمِ <tajweed class=ham_wasl>ٱ</tajweed>للَّهِ <tajweed class=ham_wasl>ٱ</tajweed><tajweed class=laam_shamsiyah>ل</tajweed>رَّحْمَ<tajweed class=madda_normal>ـٰ</tajweed>نِ <tajweed class=ham_wasl>ٱ</tajweed><tajweed class=laam_shamsiyah>ل</tajweed>رَّح<tajweed class=madda_permissible>ِي</tajweed>مِ <span class=end>١</span>"
    }
  ],
  "meta": {
    "filters": {
      "chapter_number": 1
    }
  }
}

  11. Reference Chapter Info schema

    v4.json
    The chapter-info schema provides descriptive metadata about a Quranic chapter, including long-form text (which may contain HTML), a short summary, the source of the information, and the associated language.
    {
  "chapter_id": 1,
  "text": "<h2>Name</h2><p>This Surah is named Al-Fatihah...</p>",
  "short_text": "This Surah is named Al-Fatihah...",
  "language_name": "english",
  "source": "Sayyid Abul Ala Maududi - Tafhim al-Qur'an",
  "id": 1,
  "resource_id": 58
}

  12. Quran Foundation OAuth2 API Overview

    v1.json
    The Quran Foundation OAuth2 APIs allow applications to integrate with the foundation's OAuth2 and OpenID Connect capabilities. Integration with these APIs is required to access other Quran Foundation APIs. The service provides endpoints for OpenID Connect Userinfo, OAuth2 Token Exchange, and OAuth2 Authorization.