Al-Quran Cloud API
Agent-ready OpenAPI document · curated by JenticMediaContent Deliverynone23 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read Quranic text, translations, transliterations, and audio recitations across multiple editions through 23 unauthenticated endpoints. Useful for agents building study tools, reading apps, or daily-verse delivery.
Use for: Get the text of Surah Al-Fatiha in English, Retrieve Ayat al-Kursi with an English translation, Find every ayah that contains the word 'mercy', Get the audio recitation of Surah Yasin by Abdul Basit
Not supported: Does not host hadith collections, generate AI translations, or provide tafsir commentary - use only for retrieving Quran text, audio editions, and divisions.
The Al-Quran Cloud API serves the full text of the Holy Quran along with translations, transliterations, and audio recitations across many editions and languages. Its 23 endpoints support retrieval by surah, ayah, juz, manzil, ruku, page, hizb quarter, and sajda, plus keyword search and metadata. The API is open and unauthenticated, making it well suited to mobile apps, study tools, and reading-plan integrations. Al-Quran Cloud publishes its own OpenAPI document at api.alquran.cloud/v1/documentation/openapi/yaml and renders its reference page from it; the specification behind this page is a curated Jentic variant of that document, covering 23 of its 35 operations.
Install Jentic One Beta
Connect the Al-Quran Cloud API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Al-Quran Cloud API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Falquran.cloud%2Falquran-cloud" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Falquran.cloud%2Falquran-cloud" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Al-Quran Cloud API.
Retrieve a full surah by number with the original Arabic and any chosen edition
Get a single ayah by reference (e.g., 2:255) in the original or a translation
Pull divisions of the Quran by juz, manzil, ruku, page, or hizb quarter
List all sajda ayahs from a specified edition
Search the Quran text and translations for keywords
List all available editions across languages, scripts, and recitation audio
Retrieve metadata (counts of surahs, juzs, pages, etc.) for app navigation
Use Cases
Patterns agents use Al-Quran Cloud API for, with concrete tasks.
★ Daily Verse and Reading Plan Apps
Mobile app developers wire daily-verse and structured reading-plan features off the juz, page, and ayah endpoints. The API serves both Arabic and a chosen translation in one response, so the app can show the original text and its translation side by side without managing the corpus locally.
Call GET /juz/1/quran-uthmani and GET /juz/1/en.sahih in parallel, then assemble each ayah pair into the day's reading plan view.
Quran Study and Search Tools
Study platforms expose keyword search across the original Arabic and translation editions through /search/{keyword}/{surah}/{edition}, which takes the keyword, the surah to scope to (or 'all'), and the edition as path segments, then deep-link results back to the surah/ayah views. Because the API exposes editions for transliteration and translations, the same study session can show meaning, pronunciation, and original text together.
Call GET /search/{keyword}/{surah}/{edition} with keyword 'mercy', surah 'all', and edition en.sahih, take the first match's surah and ayah, and call GET /ayah/{reference}/quran-uthmani to retrieve the original Arabic.
Audio Recitation Playback
Listen-along players use the audio editions surfaced by the API to stream recitations by reciter, surah, or ayah. The /edition endpoint lists the available recitation editions, and the surah/ayah endpoints in those editions return URLs to the audio assets, so a player can build a reciter picker without bundling audio metadata locally.
Call GET /edition?format=audio to list available reciters, then GET /surah/36/ar.alafasy to retrieve the audio URL for Surah Yasin.
AI Agent Quran Lookups via Jentic
An AI agent built on Jentic can field questions like 'show me Ayat al-Kursi in English with the Arabic' and resolve them to the right ayah-by-reference call without manual URL construction. Because the API is unauthenticated, no credentials are needed, and your own Jentic One instance logs each call it makes.
Search Jentic for 'get an ayah by reference', load the /ayah/{reference}/{edition} schema, and execute it twice for reference 2:255 with editions quran-uthmani and en.sahih.
Key Endpoints
23 endpoints — the al-quran cloud api serves the full text of the holy quran along with translations, transliterations, and audio recitations across many editions and languages.
METHOD
PATH
DESCRIPTION
GET
/surah
List all surahs
GET
/surah/{number}/{edition}
Get a surah in a specific edition
GET
/ayah/{reference}/{edition}
Get an ayah by reference in a chosen edition
GET
/juz/{number}/{edition}
Get a juz in a chosen edition
GET
/page/{number}
Get a Quran page by number
GET
/search/{keyword}/{surah}/{edition}
Search the Quran text and translations, scoped to one surah or all
GET
/edition
List available text and audio editions
GET
/meta
Get Quran metadata (counts of surahs, juzs, pages, etc.)
GET
/surah
List all surahs
GET
/surah/{number}/{edition}
Get a surah in a specific edition
GET
/ayah/{reference}/{edition}
Get an ayah by reference in a chosen edition
GET
/juz/{number}/{edition}
Get a juz in a chosen edition
GET
/page/{number}
Get a Quran page by number
GET
/search/{keyword}/{surah}/{edition}
Search the Quran text and translations, scoped to one surah or all
GET
/edition
List available text and audio editions
GET
/meta
Get Quran metadata (counts of surahs, juzs, pages, etc.)
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Al-Quran Cloud API by hand means targeting api.alquran.cloud/v1 and encoding the surah, ayah, juz, and edition reads yourself, even though it needs no auth. Through Jentic you install once, import the Al-Quran Cloud API from the API Directory, and your agent calls it with no credential to manage.
Permission scoping
The Al-Quran Cloud API puts the surah number, ayah reference, and edition in the URL path (/surah/{number}/{edition}, /ayah/{reference}/{edition}, /juz/{number}/{edition}), so a rule can pin your agent to one edition or division. This API is read-only, so you choose which of these text and audio reads the agent may call.
Credential isolation
The Al-Quran Cloud API requires no credential, so there is nothing for your Jentic One instance to store, and no secret enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'fetch a surah in a given edition' or 'search the Quran text', and Jentic returns the matching Al-Quran Cloud operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Al-Quran Cloud API through Jentic.
Does Al-Quran Cloud publish an official OpenAPI specification?
Yes. Al-Quran Cloud serves its own OpenAPI 3.1.0 document at api.alquran.cloud/v1/documentation/openapi/yaml, and its reference page at alquran.cloud/api is rendered live from it. The specification behind this page is a curated Jentic variant of that document, covering 23 of its 35 operations, so newer official routes such as the random-ayah and whole-Quran reads are not described here. To call it, install Jentic One, the self-hosted execution layer, from its GitHub repo (`https://github.com/jentic/jentic-one`).
Is there an Al-Quran Cloud MCP server?
You don't need an MCP server to give your agent the Al-Quran Cloud API. Jentic connects it directly from the API Directory: import it once and your agent calls the surah, ayah, juz, page, search, and edition reads straight from the spec, without loading another server's tool definitions into its context. Because the API is open, you have no credential to configure, so the import is the only setup step.
What authentication does the Al-Quran Cloud API use?
None. The API is fully open: the 23 operations in this spec declare no security scheme, and calls to the surah, ayah, juz, search, and edition reads return data with no API key, token, or sign-up. Through Jentic every call your agent makes is still logged by your own instance.
Can I retrieve a single ayah with translation using the Al-Quran Cloud API?
Yes. Call GET /ayah/2:255/en.sahih for a translated ayah by reference, and GET /ayah/2:255/quran-uthmani in parallel for the original Arabic. The reference format is surah:ayah.
What are the rate limits for the Al-Quran Cloud API?
Neither OpenAPI document states a limit, but the live API enforces one and advertises it on every response: the headers ratelimit-limit and x-ratelimit-limit-second both report 12 requests per second, with ratelimit-remaining counting down. Go over it and you get HTTP 429 with retry-after set to 1 second. Responses also carry cache-control max-age of 86400 seconds, so cache them for the day and back off on a 429 rather than retrying immediately.
How do I look up Ayat al-Kursi through Jentic?
Search Jentic for 'get an ayah by reference', load the /ayah/{reference}/{edition} schema, and execute with reference=2:255 and edition=en.sahih. You have no credential to configure, so the import is the only setup step.
Does the Al-Quran Cloud API serve audio recitations?
Yes. Call GET /edition with format=audio to list reciter editions, then GET /surah/{number}/{edition} (e.g., ar.alafasy) to retrieve URLs to the audio assets for that surah.
Can I limit what my agent is allowed to do with the Al-Quran Cloud API?
Yes. Because you run Jentic One yourself, your own rules decide which Al-Quran Cloud operations the agent may call, and this API is read-only, so you can permit the text and audio reads you want and block the rest. Since the surah number, ayah reference, and edition all sit in the URL path (/surah/{number}/{edition}, /ayah/{reference}/{edition}, /juz/{number}/{edition}), a rule can pin the agent to a single edition or division. The API needs no credential, so there is no secret for the agent to hold, and you control access purely by which endpoints you allow.
GET STARTED