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 x-code-samples extensions 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-by-word translation in a specific language. type default string en name in description schema words query Include words of each ayah? Use this to fetch word-by-word translation and transliteration. 0 or false will not include words. 1 or true will include the words. Default is false. type default enum string false true false name in description schema translations query comma separated ids of translations to load for each ayah. See /resources/translations for available ids. Use translations=57 to include full-ayah transliteration. type string name in description schema audio query Ayah-by-ayah recitation ID from [/resources/recitations](/docs/content_apis_versioned/recitations). Chapter-reciter IDs from [/resources/chapter_reciters](/docs/content_apis_versioned/chapter-reciters) are not supported. 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. [See full field reference](/docs/api/field-reference#translation-fields). type string name in description schema tafsir_fields query Comma separated list of tafsir fields if you want to add more fields for each tafsir. [See full field reference](/docs/api/field-reference#tafsir-fields). type string name in description schema fields query Comma-separated list of verse-level fields to include in response. Use `fields=text_uthmani,text_indopak` to include Arabic text. [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_el_hizb_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 page_number ruku_number manzil_number image_url image_width words audio translations code_v1 code_v2 v1_page v2_page rub_el_hizb_number 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 maximum minimum type 604 1 integer type integer type integer 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 604 1 integer 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 required AudioFile object verse_key url type string type string verse_key url 1:1 https://verses.quran.foundation/AbdulBaset/Mujawwad/mp3/001001.mp3 verse_key url 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 page_number rub_el_hizb_number ruku_number manzil_number foot_notes 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 type integer type integer type description additionalProperties object Map of footnote IDs to their text. Present when `foot_notes=true`. type string resource_id resource_name id text verse_id language_id language_name verse_key chapter_id verse_number juz_number hizb_number rub_el_hizb_number page_number ruku_number manzil_number foot_notes 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 1 1 1 Some editions note variant readings here. 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. type integer 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_el_hizb_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 lang label source javascript Node.js // Get random ayah const axios = require('axios'); const API_BASE_URL = 'https://apis.quran.foundation/content/api/v4'; const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'; const CLIENT_ID = '<YOUR_CLIENT_ID>'; async function callApi(options = {}) { const response = await axios.get( `${API_BASE_URL}/verses/random`, { headers: { 'x-auth-token': ACCESS_TOKEN, 'x-client-id': CLIENT_ID }, params: options } ); return response.data; } // Example usage callApi({"chapter_number":"1","page_number":"1","juz_number":"1"}) .then(data => console.log(data)) .catch(err => console.error(err.response?.status, err.message)); lang label source python Python # Get random ayah import requests API_BASE_URL = 'https://apis.quran.foundation/content/api/v4' ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>' CLIENT_ID = '<YOUR_CLIENT_ID>' def call_api(chapter_number=None, page_number=None, juz_number=None): params = {k: v for k, v in {'chapter_number': chapter_number, 'page_number': page_number, 'juz_number': juz_number}.items() if v is not None} response = requests.get( f'{API_BASE_URL}/verses/random', headers={ 'x-auth-token': ACCESS_TOKEN, 'x-client-id': CLIENT_ID }, params=params ) response.raise_for_status() return response.json() # Example usage try: data = call_api(chapter_number="1", page_number="1", juz_number="1") print(data) except requests.HTTPError as e: print(f'Error {e.response.status_code}: {e}') lang label source go Go // Get random ayah package main import ( "fmt" "io" "net/http" "net/url" ) const API_BASE_URL = "https://apis.quran.foundation/content/api/v4" const ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" const CLIENT_ID = "<YOUR_CLIENT_ID>" func callApi(params map[string]string) (string, error) { path := "/verses/random" endpoint := API_BASE_URL + path if params != nil && len(params) > 0 { values := url.Values{} for k, v := range params { values.Set(k, v) } endpoint = endpoint + "?" + values.Encode() } req, err := http.NewRequest("GET", endpoint, nil) if err != nil { return "", err } req.Header.Set("x-auth-token", ACCESS_TOKEN) req.Header.Set("x-client-id", CLIENT_ID) resp, err := http.DefaultClient.Do(req) if err != nil { return "", err } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { return "", err } return string(body), nil } // Example usage func main() { params := map[string]string{"chapter_number": "1", "page_number": "1", "juz_number": "1"} data, err := callApi(params) if err != nil { fmt.Println("Error:", err) return } fmt.Println(data) } lang label source ruby Ruby # Get random ayah require "net/http" require "uri" API_BASE_URL = "https://apis.quran.foundation/content/api/v4" ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" CLIENT_ID = "<YOUR_CLIENT_ID>" def call_api(params = {}) path = "/verses/random" uri = URI(API_BASE_URL + path) uri.query = URI.encode_www_form(params) if params && !params.empty? request_class = Net::HTTP.const_get("Get") request = request_class.new(uri) request["x-auth-token"] = ACCESS_TOKEN request["x-client-id"] = CLIENT_ID response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end response.body end # Example usage params = { "chapter_number" => "1", "page_number" => "1", "juz_number" => "1" } data = call_api(params) puts data lang label source csharp C# // Get random ayah using System; using System.Collections.Generic; using System.Linq; using System.Net.Http; using System.Threading.Tasks; const string API_BASE_URL = "https://apis.quran.foundation/content/api/v4"; const string ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"; const string CLIENT_ID = "<YOUR_CLIENT_ID>"; static async Task<string> CallApiAsync(Dictionary<string, string> query = null) { var path = $@"/verses/random"; var url = API_BASE_URL + path; if (query != null && query.Count > 0) { var queryString = string.Join("&", query.Select(kvp => $"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}")); url = $"{url}?{queryString}"; } using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), url); request.Headers.Add("x-auth-token", ACCESS_TOKEN); request.Headers.Add("x-client-id", CLIENT_ID); using var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); return await response.Content.ReadAsStringAsync(); } // Example usage var query = new Dictionary<string, string> { {"chapter_number", "1"}, {"page_number", "1"}, {"juz_number", "1"} }; var data = await CallApiAsync(query); Console.WriteLine(data); lang label source php PHP # Get random ayah <?php const API_BASE_URL = 'https://apis.quran.foundation/content/api/v4'; const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'; const CLIENT_ID = '<YOUR_CLIENT_ID>'; function callApi($params = []) { $path = "/verses/random"; $url = API_BASE_URL . $path; if (!empty($params)) { $url .= '?' . http_build_query($params); } $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'x-auth-token: ' . ACCESS_TOKEN, 'x-client-id: ' . CLIENT_ID ]); $response = curl_exec($ch); if ($response === false) { throw new Exception(curl_error($ch)); } curl_close($ch); return $response; } // Example usage $params = ['chapter_number' => '1', 'page_number' => '1', 'juz_number' => '1']; $data = callApi($params); echo $data; ?> lang label source java Java // Get random ayah import java.io.IOException; import java.util.HashMap; import java.util.Map; import okhttp3.HttpUrl; import okhttp3.OkHttpClient; import okhttp3.Request; import okhttp3.RequestBody; import okhttp3.Response; public class Main { private static final String API_BASE_URL = "https://apis.quran.foundation/content/api/v4"; private static final String ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"; private static final String CLIENT_ID = "<YOUR_CLIENT_ID>"; public static String callApi(Map<String, String> params) throws IOException { String path = "/verses/random"; HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder(); if (params != null) { for (Map.Entry<String, String> entry : params.entrySet()) { urlBuilder.addQueryParameter(entry.getKey(), entry.getValue()); } } String method = "GET"; RequestBody requestBody = method.equals("GET") ? null : RequestBody.create(new byte[0]); Request request = new Request.Builder() .url(urlBuilder.build()) .addHeader("x-auth-token", ACCESS_TOKEN) .addHeader("x-client-id", CLIENT_ID) .method(method, requestBody) .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); return response.body().string(); } public static void main(String[] args) throws Exception { Map<String, String> params = new HashMap<>(); params.put("chapter_number", "1"); params.put("page_number", "1"); params.put("juz_number", "1"); String data = callApi(params); System.out.println(data); } } lang label source powershell PowerShell # Get random ayah $API_BASE_URL = "https://apis.quran.foundation/content/api/v4" $ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" $CLIENT_ID = "<YOUR_CLIENT_ID>" function Call-Api([hashtable]$params = @{}) { $path = "/verses/random" $url = "$API_BASE_URL$path" if ($params.Count -gt 0) { $query = ($params.GetEnumerator() | ForEach-Object { "$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))" }) -join "&" $url = "$url?$query" } $headers = @{ "x-auth-token" = $ACCESS_TOKEN "x-client-id" = $CLIENT_ID } Invoke-RestMethod -Method GET -Uri $url -Headers $headers } # Example usage $params = @{ chapter_number = "1"; page_number = "1"; juz_number = "1" } $data = Call-Api($params) Write-Output $data lang label source bash cURL # Get random ayah curl -X GET \ 'https://apis.quran.foundation/content/api/v4/verses/random?chapter_number=1&page_number=1&juz_number=1' \ -H 'x-auth-token: <YOUR_ACCESS_TOKEN>' \ -H 'x-client-id: <YOUR_CLIENT_ID>' lang label source text 🤖 AI Prompt Implement a function to get random ayah using the Quran Foundation API. Endpoint: GET /verses/random Base URL: https://apis.quran.foundation/content/api/v4 Required Headers (copy exactly): x-auth-token: <YOUR_ACCESS_TOKEN> x-client-id: <YOUR_CLIENT_ID> Optional Query Parameters: chapter_number: Return a random verse **only from the specified chapter (sūrah)**. page_number: Return a random verse **only from the specified Muṣḥaf page** (1 – 604). juz_number: Return a random verse **only from the specified juzʾ** (1 – 30). hizb_number: Return a random verse **only from the specified ḥizb** (1 – 60). rub_el_hizb_number: Return a random verse **only from the specified rubʿ al-ḥizb** (1 – 240). Implementation Requirements: 1. Build the request URL: {baseUrl}/verses/random?{queryParams} 2. Inject both required headers on every request 3. Handle errors safely: - 401: Token expired → re-request token and retry once - 403: Access denied → check client credentials - 429: Rate limited → implement exponential backoff Acceptance Checklist: - [ ] Function accepts optional parameters - [ ] Headers x-auth-token and x-client-id are sent - [ ] 401/403/429 errors are handled gracefully key value x-code-samples lang label source javascript Node.js // Get random ayah const axios = require('axios'); const API_BASE_URL = 'https://apis.quran.foundation/content/api/v4'; const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'; const CLIENT_ID = '<YOUR_CLIENT_ID>'; async function callApi(options = {}) { const response = await axios.get( `${API_BASE_URL}/verses/random`, { headers: { 'x-auth-token': ACCESS_TOKEN, 'x-client-id': CLIENT_ID }, params: options } ); return response.data; } // Example usage callApi({"chapter_number":"1","page_number":"1","juz_number":"1"}) .then(data => console.log(data)) .catch(err => console.error(err.response?.status, err.message)); lang label source python Python # Get random ayah import requests API_BASE_URL = 'https://apis.quran.foundation/content/api/v4' ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>' CLIENT_ID = '<YOUR_CLIENT_ID>' def call_api(chapter_number=None, page_number=None, juz_number=None): params = {k: v for k, v in {'chapter_number': chapter_number, 'page_number': page_number, 'juz_number': juz_number}.items() if v is not None} response = requests.get( f'{API_BASE_URL}/verses/random', headers={ 'x-auth-token': ACCESS_TOKEN, 'x-client-id': CLIENT_ID }, params=params ) response.raise_for_status() return response.json() # Example usage try: data = call_api(chapter_number="1", page_number="1", juz_number="1") print(data) except requests.HTTPError as e: print(f'Error {e.response.status_code}: {e}') lang label source go Go // Get random ayah package main import ( "fmt" "io" "net/http" "net/url" ) const API_BASE_URL = "https://apis.quran.foundation/content/api/v4" const ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" const CLIENT_ID = "<YOUR_CLIENT_ID>" func callApi(params map[string]string) (string, error) { path := "/verses/random" endpoint := API_BASE_URL + path if params != nil && len(params) > 0 { values := url.Values{} for k, v := range params { values.Set(k, v) } endpoint = endpoint + "?" + values.Encode() } req, err := http.NewRequest("GET", endpoint, nil) if err != nil { return "", err } req.Header.Set("x-auth-token", ACCESS_TOKEN) req.Header.Set("x-client-id", CLIENT_ID) resp, err := http.DefaultClient.Do(req) if err != nil { return "", err } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { return "", err } return string(body), nil } // Example usage func main() { params := map[string]string{"chapter_number": "1", "page_number": "1", "juz_number": "1"} data, err := callApi(params) if err != nil { fmt.Println("Error:", err) return } fmt.Println(data) } lang label source ruby Ruby # Get random ayah require "net/http" require "uri" API_BASE_URL = "https://apis.quran.foundation/content/api/v4" ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" CLIENT_ID = "<YOUR_CLIENT_ID>" def call_api(params = {}) path = "/verses/random" uri = URI(API_BASE_URL + path) uri.query = URI.encode_www_form(params) if params && !params.empty? request_class = Net::HTTP.const_get("Get") request = request_class.new(uri) request["x-auth-token"] = ACCESS_TOKEN request["x-client-id"] = CLIENT_ID response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| http.request(request) end response.body end # Example usage params = { "chapter_number" => "1", "page_number" => "1", "juz_number" => "1" } data = call_api(params) puts data lang label source csharp C# // Get random ayah using System; using System.Collections.Generic; using System.Linq; using System.Net.Http; using System.Threading.Tasks; const string API_BASE_URL = "https://apis.quran.foundation/content/api/v4"; const string ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"; const string CLIENT_ID = "<YOUR_CLIENT_ID>"; static async Task<string> CallApiAsync(Dictionary<string, string> query = null) { var path = $@"/verses/random"; var url = API_BASE_URL + path; if (query != null && query.Count > 0) { var queryString = string.Join("&", query.Select(kvp => $"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}")); url = $"{url}?{queryString}"; } using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), url); request.Headers.Add("x-auth-token", ACCESS_TOKEN); request.Headers.Add("x-client-id", CLIENT_ID); using var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); return await response.Content.ReadAsStringAsync(); } // Example usage var query = new Dictionary<string, string> { {"chapter_number", "1"}, {"page_number", "1"}, {"juz_number", "1"} }; var data = await CallApiAsync(query); Console.WriteLine(data); lang label source php PHP # Get random ayah <?php const API_BASE_URL = 'https://apis.quran.foundation/content/api/v4'; const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'; const CLIENT_ID = '<YOUR_CLIENT_ID>'; function callApi($params = []) { $path = "/verses/random"; $url = API_BASE_URL . $path; if (!empty($params)) { $url .= '?' . http_build_query($params); } $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'x-auth-token: ' . ACCESS_TOKEN, 'x-client-id: ' . CLIENT_ID ]); $response = curl_exec($ch); if ($response === false) { throw new Exception(curl_error($ch)); } curl_close($ch); return $response; } // Example usage $params = ['chapter_number' => '1', 'page_number' => '1', 'juz_number' => '1']; $data = callApi($params); echo $data; ?> lang label source java Java // Get random ayah import java.io.IOException; import java.util.HashMap; import java.util.Map; import okhttp3.HttpUrl; import okhttp3.OkHttpClient; import okhttp3.Request; import okhttp3.RequestBody; import okhttp3.Response; public class Main { private static final String API_BASE_URL = "https://apis.quran.foundation/content/api/v4"; private static final String ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"; private static final String CLIENT_ID = "<YOUR_CLIENT_ID>"; public static String callApi(Map<String, String> params) throws IOException { String path = "/verses/random"; HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder(); if (params != null) { for (Map.Entry<String, String> entry : params.entrySet()) { urlBuilder.addQueryParameter(entry.getKey(), entry.getValue()); } } String method = "GET"; RequestBody requestBody = method.equals("GET") ? null : RequestBody.create(new byte[0]); Request request = new Request.Builder() .url(urlBuilder.build()) .addHeader("x-auth-token", ACCESS_TOKEN) .addHeader("x-client-id", CLIENT_ID) .method(method, requestBody) .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); return response.body().string(); } public static void main(String[] args) throws Exception { Map<String, String> params = new HashMap<>(); params.put("chapter_number", "1"); params.put("page_number", "1"); params.put("juz_number", "1"); String data = callApi(params); System.out.println(data); } } lang label source powershell PowerShell # Get random ayah $API_BASE_URL = "https://apis.quran.foundation/content/api/v4" $ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>" $CLIENT_ID = "<YOUR_CLIENT_ID>" function Call-Api([hashtable]$params = @{}) { $path = "/verses/random" $url = "$API_BASE_URL$path" if ($params.Count -gt 0) { $query = ($params.GetEnumerator() | ForEach-Object { "$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))" }) -join "&" $url = "$url?$query" } $headers = @{ "x-auth-token" = $ACCESS_TOKEN "x-client-id" = $CLIENT_ID } Invoke-RestMethod -Method GET -Uri $url -Headers $headers } # Example usage $params = @{ chapter_number = "1"; page_number = "1"; juz_number = "1" } $data = Call-Api($params) Write-Output $data lang label source bash cURL # Get random ayah curl -X GET \ 'https://apis.quran.foundation/content/api/v4/verses/random?chapter_number=1&page_number=1&juz_number=1' \ -H 'x-auth-token: <YOUR_ACCESS_TOKEN>' \ -H 'x-client-id: <YOUR_CLIENT_ID>' lang label source text 🤖 AI Prompt Implement a function to get random ayah using the Quran Foundation API. Endpoint: GET /verses/random Base URL: https://apis.quran.foundation/content/api/v4 Required Headers (copy exactly): x-auth-token: <YOUR_ACCESS_TOKEN> x-client-id: <YOUR_CLIENT_ID> Optional Query Parameters: chapter_number: Return a random verse **only from the specified chapter (sūrah)**. page_number: Return a random verse **only from the specified Muṣḥaf page** (1 – 604). juz_number: Return a random verse **only from the specified juzʾ** (1 – 30). hizb_number: Return a random verse **only from the specified ḥizb** (1 – 60). rub_el_hizb_number: Return a random verse **only from the specified rubʿ al-ḥizb** (1 – 240). Implementation Requirements: 1. Build the request URL: {baseUrl}/verses/random?{queryParams} 2. Inject both required headers on every request 3. Handle errors safely: - 401: Token expired → re-request token and retry once - 403: Access denied → check client credentials - 429: Rate limited → implement exponential backoff Acceptance Checklist: - [ ] Function accepts optional parameters - [ ] Headers x-auth-token and x-client-id are sent - [ ] 401/403/429 errors are handled gracefully 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 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. ```mermaid sequenceDiagram participant App as Your App participant Auth as Quran.Foundation<br/>Authorization Server participant API as Quran.Foundation<br/>Resources Server App->>Auth: Request Token with Client Credentials Auth-->>App: Token Response (access_token) App->>API: Use token to call API API-->>App: Requested resource Note over App,Auth: Access token expires (1 hour) App->>Auth: Re-issue access_token using client_credentials Auth-->>App: New access_token ``` 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`. This spec also includes a small subset of Quran Reflect post-read endpoints that are compatible with the `client_credentials` grant. These operations still require `x-auth-token` and `x-client-id`, but they do not use the `content` scope. Use `post.read` for `/quran-reflect/v1/posts/feed`, `/quran-reflect/v1/posts/{id}`, and `/quran-reflect/v1/posts/user-posts/{id}`. Use `comment.read` for `/quran-reflect/v1/posts/{id}/comments` and `/quran-reflect/v1/posts/{id}/all-comments`. These are Quran Reflect gateway endpoints, not `/content/api/v4/...` endpoints. 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-by-word translation in a specific language. text/plain language disabled description key value false content type Include words of each ayah? Use this to fetch word-by-word translation and transliteration. 0 or false will not include words. 1 or true will include the words. Default is false. 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. Use translations=57 to include full-ayah transliteration. text/plain translations disabled description key value false content type Ayah-by-ayah recitation ID from [/resources/recitations](/docs/content_apis_versioned/recitations). Chapter-reciter IDs from [/resources/chapter_reciters](/docs/content_apis_versioned/chapter-reciters) are not supported. 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. [See full field reference](/docs/api/field-reference#translation-fields). text/plain translation_fields disabled description key value false content type Comma separated list of tafsir fields if you want to add more fields for each tafsir. [See full field reference](/docs/api/field-reference#tafsir-fields). text/plain tafsir_fields disabled description key value false content type Comma-separated list of verse-level fields to include in response. Use `fields=text_uthmani,text_indopak` to include Arabic text. [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
displayed_sidebar	APIsSidebar

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"}}>
words object[]
Array [
= 1` and `<= 604`"} schema={{"maximum":604,"minimum":1,"type":"integer"}}>
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 [
foot_notes object
Map of footnote IDs to their text. Present when foot_notes=true.
]
= 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_el_hizb_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