random-verse.api.mdx

id	random-verse
title	Get random ayah
description	Get a random verse. You can get random verse from a specific `chapter`,`page`, `juz`, `hizb`, `rub-el-hizb`, `ruku`, `manzil`, or from whole Quran.
sidebar_label	Get random ayah
hide_title	true
hide_table_of_contents	true
api	tags description operationId parameters responses method path servers security securitySchemes info postman Verses Get a random verse. You can get random verse from a specific `chapter`,`page`, `juz`, `hizb`, `rub-el-hizb`, `ruku`, `manzil`, or from whole Quran. random_verse name in description schema chapter_number query Return a random verse **only from the specified chapter (sūrah)**. type minimum maximum integer 1 114 name in description schema page_number query Return a random verse **only from the specified Muṣḥaf page** (1 – 604). type minimum maximum integer 1 604 name in description schema juz_number query Return a random verse **only from the specified juzʾ** (1 – 30). type minimum maximum integer 1 30 name in description schema hizb_number query Return a random verse **only from the specified ḥizb** (1 – 60). type minimum maximum integer 1 60 name in description schema rub_el_hizb_number query Return a random verse **only from the specified rubʿ al-ḥizb** (1 – 240). type minimum maximum integer 1 240 name in description schema ruku_number query Return a random verse **only from the specified rukūʿ**. type minimum integer 1 name in description schema manzil_number query Return a random verse **only from the specified manzil** (1 – 7). type minimum maximum integer 1 7 name in description schema language query Language to fetch word translation in specific language. type default string en name in description schema words query Include words of each ayah? 0 or false will not include words. 1 or true will include the words. type default enum string true true false name in description schema translations query comma separated ids of translations to load for each ayah. See /resources/translations for available ids. type string name in description schema audio query Id of recitation if you want to load audio of each ayah. type integer name in description schema tafsirs query Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See /resources/tafsirs for available ids. type string name in description schema word_fields query Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields). type string name in description schema translation_fields query Comma separated list of translation fields if you want to add more fields for each translation. type string name in description schema fields query Comma-separated list of verse-level fields to include in response. [See full field reference](/docs/api/field-reference#verse-level-fields). type string 200 400 401 403 404 422 429 500 502 503 504 description content Successful response application/json schema example required type properties verse object verse title required type properties example Verse hizb_number id juz_number page_number rub_number verse_key verse_number object id chapter_id verse_number verse_key verse_index text_uthmani text_uthmani_simple text_imlaei text_imlaei_simple text_indopak text_uthmani_tajweed juz_number hizb_number rub_number page_number image_url image_width words audio translations code_v1 code_v2 v1_page v2_page type integer type description integer Chapter number of this verse type integer type description string key of the verse, key is generated using chapter number and ayah number. e.g 1:1 is first ayah of first surah. type integer type description string Ayah text in Uthmani Script. Uthmani script is an old-fashion script used by the third Caliph, Uthman, to produce the first standard quran manuscript. type description string Uthmani script diacritic marks type description string Ayah text in Imla'ei script. Imla'ei script, is the modern Arabic writing style which is currently in use. type string type string type string type integer type integer type integer maximum minimum type description 604 1 integer page_number is deprecated, please use `v1_page` instead. type string type integer type items array title required type properties example Word audio_url char_type_name position translation transliteration object id position text_uthmani text_indopak text_imlaei verse_key page_number line_number audio_url location char_type_name code_v1 code_v2 translation transliteration v1_page v2_page type integer type description integer Word position within ayah type description string Word text in Uthmanic script type string type description string Word text in simple/Imlaei script type string maximum minimum type description 604 1 integer page_number is deprecated, please use `v1_page` instead. type description integer Line number in the Mushaf for this word type string type string type string type description string glyph code that you can use to render the word using QCF v1 font. type description string glyph code that you can use to render the word using QCF v2 font. type properties object text language_name type string type string type properties object text language_name type string type string maximum minimum type description 604 1 integer Madani Mushaf Page number for v1 font. If `v1_page` value is 2, that means you'll use page 2 font file to render this word using v1 glyph codes. maximum minimum type description 604 1 integer Madani Mushaf Page number for v2 font. If `v2_page` value is 2, that means you'll use page 2 font file to render this ayah using v2 glyph codes. id position text_uthmani text_indopak text_imlaei verse_key page_number line_number audio_url location char_type_name code_v1 translation transliteration 1 1 بِسْمِ بِسۡمِ بِسْمِ 1:1 1 2 wbw/001_001_001.mp3 1:1:1 word &#xfb51; text language_name In (the) name english text language_name bis'mi english title type properties example AudioFile object url duration format segments type string type number type string type items array type object url duration format segments https://verses.quran.foundation/AbdulBaset/Mujawwad/mp3/001001.mp3 6 mp3 0 120 -1 120 420 0 540 810 1 1350 1006 2 2356 2454 3 4810 390 -1 type items array title required type properties example Translation resource_id text object resource_id resource_name id text verse_id language_id language_name verse_key chapter_id verse_number juz_number hizb_number rub_number page_number type integer type string type integer type description string Text of the translation, text could have HTML tags for formatting and footnotes. type integer type integer type string type string type integer type integer type integer type integer type integer type integer resource_id resource_name id text verse_id language_id language_name verse_key chapter_id verse_number juz_number hizb_number rub_number page_number 131 Dr. Mustafa Khattab, the Clear Quran 903958 In the Name of Allah—the Most Compassionate, Most Merciful. 1 38 english 1:1 1 1 1 1 1 1 type description string Glyphs codes for QCF v1 fonts type description string Glyphs codes for QCF v2 fonts maximum minimum type description 604 1 integer Madani Mushaf Page number for v1 font. If `v1_page` value is 2, that means you'll use page 2 font file to render this ayah using v1 glyph codes. maximum minimum type description 604 1 integer Madani Mushaf Page number for v2 font. If `v2_page` value is 2, that means you'll use page 2 font file to render this ayah using v2 glyph codes. id chapter_id verse_number verse_key verse_index text_uthmani text_uthmani_simple text_imlaei text_imlaei_simple text_indopak text_uthmani_tajweed juz_number hizb_number rub_number page_number image_url image_width words 1 1 1 1:1 1 بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ بسم الله الرحمن الرحيم بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ بسم الله الرحمن الرحيم بِسۡمِ اللهِ الرَّحۡمٰنِ الرَّحِيۡمِ بِسْمِ <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> 1 1 1 1 //c22506.r6.cf1.rackcdn.com/1_1.png 675 id position audio_url char_type_name translation transliteration 1 1 wbw/001_001_001.mp3 word text language_name In (the) name english text language_name bis'mi english verse id verse_number page_number verse_key juz_number hizb_number rub_el_hizb_number sajdah_type sajdah_number words translations tafsirs 1 1 1 1:1 1 1 1 id position audio_url char_type_name line_number page_number code_v1 translation transliteration 1 1 wbw/001_001_001.mp3 word 2 1 &#xfb51; text language_name In (the) name english text language_name bis'mi english resource_id text 131 In the Name of Allah—the Most Compassionate, Most Merciful. id language_name name text 82641 english Tafsir Ibn Kathir <h2 class="title">Which was revealed in Makkah</h2><h2 class="title">The Meaning of Al-Fatihah and its Various Names</h2> description content Will be returned when the request is invalid e.g. request is missing required headers or with invalid query parameters. application/json schema example title type properties invalidRequestResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The request is missing required headers or is invalid invalid_request false description content Will be returned when the request is unauthorized. application/json schema example title type properties unauthorizedResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The request requires user authentication unauthorized false description content Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions. application/json schema example title type properties forbiddenResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The server understood the request, but refuses to authorize it forbidden false description content Not Found. The resource being accessed does not exist. application/json schema example title type properties notFoundResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The requested resource could not be found not_found false description content Validation Error. The request includes one or more invalid params. Please check the request params and try again. application/json schema example title type properties unprocessableEntityResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The request was well-formed but was unable to be followed due to semantic errors unprocessable_entity false description content Rate-limit exceeded application/json schema example title type properties rateLimitExceededResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success Too many requests, please try again later rate_limit_exceeded false description content Server Error. Something went wrong, try again later. application/json schema example title type properties internalServerErrorResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The server encountered an internal error and was unable to complete your request internal_server_error false description content Bad Gateway application/json schema example title type properties badGatewayResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The server was acting as a gateway or proxy and received an invalid response from the upstream server bad_gateway false description content Service Unavailable application/json schema example title type properties serviceUnavailableResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The server is currently unable to handle the request due to a temporary overload or scheduled maintenance service_unavailable false description content Gateway Timeout application/json schema example title type properties gatewayTimeoutResponse object message type success type string type enum string gateway_timeout service_unavailable bad_gateway internal_server_error unprocessable_entity not_found forbidden unauthorized invalid_request invalid_token insufficient_scope service_error invalid_path rate_limit_exceeded type boolean message type success The server was acting as a gateway or proxy and did not receive a timely response from the upstream server gateway_timeout false get /verses/random url description https://apis-prelive.quran.foundation/content/api/v4 Pre-production Server url description https://apis.quran.foundation/content/api/v4 Production Server x-auth-token x-client-id x-auth-token x-client-id type description name in apiKey The JWT access token required for accessing the endpoints. x-auth-token header type description name in apiKey Your client Id x-client-id header title description version Content APIs Quran.Foundation Content APIs offer programmatic access to the Quran's core content like chapters, verses, recitations, translations, and more, distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis). :::important Integrity of Translations Please **disable any automatic browser-translation features** (e.g. Google-Translate-in-Chrome) when displaying text returned by the *Translations* endpoints. Re-translating an already vetted Quranic translation can introduce serious semantic errors. ::: ## How to get access We are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Since the APIs are not user-related, you will need to use the `client_credentials` grant type and [`content` scope](/docs/user_related_apis_versioned/scopes#content) when sending a request to [The OAuth 2.0 Token Endpoint](/docs/oauth2_apis_versioned/oauth-2-token-exchange) to get the access token. The below diagram shows the flow of getting an access token using the `client_credentials` grant type in a very simplified way.  After getting a valid access token, each request to get resources will have to include 2 headers mentioned below: `x-auth-token` and `x-client-id`. v4 name description url header method Get random ayah content type Get a random verse. You can get random verse from a specific `chapter`,`page`, `juz`, `hizb`, `rub-el-hizb`, `ruku`, `manzil`, or from whole Quran. text/plain path host query variable verses random {{baseUrl}} disabled description key value false content type Return a random verse **only from the specified chapter (sūrah)**. text/plain chapter_number disabled description key value false content type Return a random verse **only from the specified Muṣḥaf page** (1 – 604). text/plain page_number disabled description key value false content type Return a random verse **only from the specified juzʾ** (1 – 30). text/plain juz_number disabled description key value false content type Return a random verse **only from the specified ḥizb** (1 – 60). text/plain hizb_number disabled description key value false content type Return a random verse **only from the specified rubʿ al-ḥizb** (1 – 240). text/plain rub_el_hizb_number disabled description key value false content type Return a random verse **only from the specified rukūʿ**. text/plain ruku_number disabled description key value false content type Return a random verse **only from the specified manzil** (1 – 7). text/plain manzil_number disabled description key value false content type Language to fetch word translation in specific language. text/plain language disabled description key value false content type Include words of each ayah? 0 or false will not include words. 1 or true will include the words. text/plain words disabled description key value false content type comma separated ids of translations to load for each ayah. See /resources/translations for available ids. text/plain translations disabled description key value false content type Id of recitation if you want to load audio of each ayah. text/plain audio disabled description key value false content type Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See /resources/tafsirs for available ids. text/plain tafsirs disabled description key value false content type Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields). text/plain word_fields disabled description key value false content type Comma separated list of translation fields if you want to add more fields for each translation. text/plain translation_fields disabled description key value false content type Comma-separated list of verse-level fields to include in response. [See full field reference](/docs/api/field-reference#verse-level-fields). text/plain fields key value Accept application/json GET
sidebar_class_name	get api-method
info_path	docs/content_apis_versioned/content-apis
custom_edit_url

import ApiTabs from "@theme/ApiTabs"; import MimeTabs from "@theme/MimeTabs"; import ParamsItem from "@theme/ParamsItem"; import ResponseSamples from "@theme/ResponseSamples"; import SchemaItem from "@theme/SchemaItem"; import SchemaTabs from "@theme/SchemaTabs"; import DiscriminatorTabs from "@theme/DiscriminatorTabs"; import TabItem from "@theme/TabItem";

Get random ayah

Get a random verse. You can get random verse from a specific chapter,page, juz, hizb, rub-el-hizb, ruku, manzil, or from whole Quran.

Query Parameters

Successful response

Schema

verse object required
= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"page_number is deprecated, please use `v1_page` instead."}}>
words object[]
Array [
= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"page_number is deprecated, please use `v1_page` instead."}}>
translation object required
transliteration object required
= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"Madani Mushaf Page number for v1 font. If `v1_page` value is 2, that means you'll use page 2 font file to render this word using v1 glyph codes."}}>= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"Madani Mushaf Page number for v2 font. If `v2_page` value is 2, that means you'll use page 2 font file to render this ayah using v2 glyph codes."}}>
]
audio object
translations object[]
Array [
]
= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"Madani Mushaf Page number for v1 font. If `v1_page` value is 2, that means you'll use page 2 font file to render this ayah using v1 glyph codes."}}>= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer","description":"Madani Mushaf Page number for v2 font. If `v2_page` value is 2, that means you'll use page 2 font file to render this ayah using v2 glyph codes."}}>

ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ ١\",\n \"juz_number\": 1,\n \"hizb_number\": 1,\n \"rub_number\": 1,\n \"page_number\": 1,\n \"image_url\": \"//c22506.r6.cf1.rackcdn.com/1_1.png\",\n \"image_width\": 675,\n \"words\": [\n {\n \"id\": 1,\n \"position\": 1,\n \"audio_url\": \"wbw/001_001_001.mp3\",\n \"char_type_name\": \"word\",\n \"translation\": {\n \"text\": \"In (the) name\",\n \"language_name\": \"english\"\n },\n \"transliteration\": {\n \"text\": \"bis'mi\",\n \"language_name\": \"english\"\n }\n }\n ]\n }\n}"} language={"json"}>Which was revealed in Makkah

The Meaning of Al-Fatihah and its Various Names

\"\n }\n ]\n }\n}"} language={"json"}>

Will be returned when the request is invalid e.g. request is missing required headers or with invalid query parameters.

Schema

Will be returned when the request is unauthorized.

Schema

Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions.

Schema

Not Found. The resource being accessed does not exist.

Schema

Validation Error. The request includes one or more invalid params. Please check the request params and try again.

Schema

Rate-limit exceeded

Schema

Server Error. Something went wrong, try again later.

Schema

Bad Gateway

Schema

Service Unavailable

Schema

Gateway Timeout

Schema