Python SDK

The Python SDK is the official package for server-side Python applications, scripts, jobs, notebooks, and AI workflows. It is published on PyPI as quran-foundation-api and imports as quran_foundation.

Use it from trusted server-side environments. Do not expose client_secret, access tokens, or refresh tokens in browser code, mobile bundles, public notebooks, logs, or generated client-side code.

Installation

Install the released package from PyPI:

python -m pip install quran-foundation-api

First Call

Create a QuranClient with your Quran Foundation client_id and an access_token. Use an app access token from the client credentials flow for Content and Search API calls. Use a user access token from the OAuth2 authorization flow for signed-in User API calls.

from quran_foundation import QuranClient

with QuranClient(client_id="YOUR_CLIENT_ID", access_token="APP_ACCESS_TOKEN") as client:
    chapters = client.list_chapters(language="en")
    verse = client.get_verse_by_key("2:255", translations="131")

QuranClient adds the required x-client-id header, adds x-auth-token from access_token, removes None query parameters, parses JSON responses, and raises SDK exceptions for failed HTTP responses.

What To Read Next

• Authentication - app tokens, user tokens, and OAuth2 helpers
• Content API Helpers - helper coverage and raw Content endpoint calls
• Chapters API
• Verses API
• Audio API
• Resources API
• Answers API
• Hadith References API
• Juzs API
• Search API
• User APIs
• Common Errors

Runtime Guidance

• Use the Python SDK from trusted server-side environments.
• Keep client_secret, access tokens, and refresh tokens out of frontend and mobile code.
• Use environment variables or a secret manager for credentials.
• Use manual authentication when you want to inspect the raw token flow.
• Use the JavaScript SDK when you are building in Node.js, browser apps, or TypeScript-first full-stack applications.