\nPath Parameters:\n id: Chapter ID ( 1-114) (e.g., \"1\")\nOptional Query Parameters:\n language: Optional parameter\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/chapters/{id}?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts id and optional parameters\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/chapters/{id}/info": {
"get": {
"tags": ["Chapters"],
"summary": "Get Chapter Info",
"description": "Get Chapter Info in specific language. Default to `English`. Supports selecting a specific resource via `resource_id` and listing available resources via `include_resources=true`. Use `include_resources=true` to discover the resource ids or slugs that actually have chapter-info content for the resolved chapter and language. The [`/resources/chapter_infos`](/docs/content_apis_versioned/chapter-info) endpoint is a global catalog of chapter-info resources and may include resources that return `chapter_info: null` for a specific chapter.",
"operationId": "get-chapter-info",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Chapter number (1-114)",
"required": true,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 114
}
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
},
"description": "Language ISO code for translated metadata. Defaults to English."
},
{
"name": "locale",
"in": "query",
"schema": {
"type": "string"
},
"description": "Locale fallback if a language code is not provided."
},
{
"name": "resource_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Resource id or slug of the chapter info resource to fetch. Prefer identifiers returned by `include_resources=true` for the current chapter. The [`/resources/chapter_infos`](/docs/content_apis_versioned/chapter-info) endpoint is a global catalog and may include resources that do not have chapter-info content for this specific chapter, which would return `chapter_info: null`."
},
{
"name": "include_resources",
"in": "query",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
},
"description": "Include the ordered list of available chapter info resources that actually have content for the resolved chapter and language. This is the safest discovery path for the id or slug to pass as `resource_id` for a specific author such as Ibn Ashur."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"chapter_info": {
"allOf": [
{
"$ref": "#/components/schemas/chapter-info"
}
],
"nullable": true,
"description": "Resolved chapter info resource. Returns `null` when the requested `resource_id` does not match an approved chapter info resource for the resolved chapter and language, or when the selected resource has no chapter-info content for that chapter after language resolution."
},
"resources": {
"description": "Only returned when `include_resources=true`. Contains approved chapter info resources that have chapter-info content for the resolved chapter and language, ordered by the API's preferred resource order for selection.",
"type": "array",
"items": {
"$ref": "#/components/schemas/resource"
}
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"chapter_info": {
"id": 1,
"chapter_id": 1,
"language_name": "english",
"short_text": "This Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.",
"source": "Sayyid Abul Ala Maududi - Tafhim al-Qur'an - The Meaning of the Quran",
"text": "Name
\r\nThis Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.
\r\nPeriod of Revelation
...",
"resource_id": 58
},
"resources": [
{
"id": 58,
"name": "Chapter Info",
"author_name": "Sayyid Abul Ala Maududi",
"slug": "",
"language_name": "english",
"translated_name": {
"name": "Chapter Info",
"language_name": "english"
}
}
]
}
},
"resolved_with_resources": {
"summary": "Resolved chapter info with resource list",
"value": {
"chapter_info": {
"id": 1,
"chapter_id": 1,
"language_name": "english",
"short_text": "This Surah is named Al-Fatihah because it opens the Book.",
"source": "Sayyid Abul Ala Maududi - Tafhim al-Qur'an - The Meaning of the Quran",
"text": "Name
This Surah is named Al-Fatihah because it opens the Book.
",
"resource_id": 58
},
"resources": [
{
"id": 58,
"name": "Chapter Info",
"author_name": "Sayyid Abul Ala Maududi",
"slug": "chapter-info-maududi",
"language_name": "english",
"translated_name": {
"name": "Chapter Info",
"language_name": "english"
}
}
]
}
},
"no_matching_resource": {
"summary": "No approved chapter info for selected resource",
"value": {
"chapter_info": null,
"resources": []
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// Get Chapter Info\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(id, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/chapters/${id}/info`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\n// Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\ncallApi(\"1\", {\"language\":\"en\",\"resource_id\":\"58\",\"include_resources\":\"true\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# Get Chapter Info\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(id, language=None, locale=None, resource_id=None, include_resources=None):\n params = {k: v for k, v in {\n 'language': language,\n 'locale': locale,\n 'resource_id': resource_id,\n 'include_resources': include_resources,\n }.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/chapters/{id}/info',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\n# Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\ntry:\n data = call_api(\"1\", language=\"en\", resource_id=\"58\", include_resources=\"true\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// Get Chapter Info\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(id string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/chapters/%s/info\", id)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\n// Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"resource_id\": \"58\", \"include_resources\": \"true\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# Get Chapter Info\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(id, params = {})\n path = \"/chapters/#{id}/info\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\n# Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\nparams = { \"language\" => \"en\", \"resource_id\" => \"58\", \"include_resources\" => \"true\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// Get Chapter Info\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string id, Dictionary query = null)\n{\n var path = $@\"/chapters/{id}/info\";\n var url = API_BASE_URL + path;\n if (query != null && query.Count > 0)\n {\n var queryString = string.Join(\"&\", query.Select(kvp =>\n $\"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}\"));\n url = $\"{url}?{queryString}\";\n }\n using var client = new HttpClient();\n using var request = new HttpRequestMessage(new HttpMethod(\"GET\"), url);\n request.Headers.Add(\"x-auth-token\", ACCESS_TOKEN);\n request.Headers.Add(\"x-client-id\", CLIENT_ID);\n\n using var response = await client.SendAsync(request);\n response.EnsureSuccessStatusCode();\n return await response.Content.ReadAsStringAsync();\n}\n\n// Example usage\n// Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\nvar query = new Dictionary { {\"language\", \"en\"}, {\"resource_id\", \"58\"}, {\"include_resources\", \"true\"} };\nvar data = await CallApiAsync(\"1\", query);\nConsole.WriteLine(data);"
},
{
"lang": "php",
"label": "PHP",
"source": "# Get Chapter Info\n';\nconst CLIENT_ID = '';\n\nfunction callApi($id, $params = []) {\n $path = sprintf(\"/chapters/%s/info\", $id);\n $url = API_BASE_URL . $path;\n if (!empty($params)) {\n $url .= '?' . http_build_query($params);\n }\n $ch = curl_init($url);\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');\n curl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'x-auth-token: ' . ACCESS_TOKEN,\n 'x-client-id: ' . CLIENT_ID\n ]);\n\n $response = curl_exec($ch);\n if ($response === false) {\n throw new Exception(curl_error($ch));\n }\n curl_close($ch);\n return $response;\n}\n\n// Example usage\n// Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\n$params = ['language' => 'en', 'resource_id' => '58', 'include_resources' => 'true'];\n$data = callApi(\"1\", $params);\necho $data;\n?>"
},
{
"lang": "java",
"label": "Java",
"source": "// Get Chapter Info\nimport java.io.IOException;\nimport java.util.HashMap;\nimport java.util.Map;\nimport okhttp3.HttpUrl;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\n\npublic class Main {\n private static final String API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\n private static final String ACCESS_TOKEN = \"\";\n private static final String CLIENT_ID = \"\";\n\n public static String callApi(String id, Map params) throws IOException {\n String path = String.format(\"/chapters/%s/info\", id);\n HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();\n if (params != null) {\n for (Map.Entry entry : params.entrySet()) {\n urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n String method = \"GET\";\n RequestBody requestBody = method.equals(\"GET\") ? null : RequestBody.create(new byte[0]);\n Request request = new Request.Builder()\n .url(urlBuilder.build())\n .addHeader(\"x-auth-token\", ACCESS_TOKEN)\n .addHeader(\"x-client-id\", CLIENT_ID)\n .method(method, requestBody)\n .build();\n\n OkHttpClient client = new OkHttpClient();\n Response response = client.newCall(request).execute();\n return response.body().string();\n }\n\n public static void main(String[] args) throws Exception {\n // Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\n Map params = new HashMap<>();\n params.put(\"language\", \"en\");\n params.put(\"resource_id\", \"58\");\n params.put(\"include_resources\", \"true\");\n String data = callApi(\"1\", params);\n System.out.println(data);\n }\n}"
},
{
"lang": "powershell",
"label": "PowerShell",
"source": "# Get Chapter Info\n$API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\n$ACCESS_TOKEN = \"\"\n$CLIENT_ID = \"\"\n\nfunction Call-Api([string]$id, [hashtable]$params = @{}) {\n $path = \"/chapters/$id/info\"\n $url = \"$API_BASE_URL$path\"\n if ($params.Count -gt 0) {\n $query = ($params.GetEnumerator() | ForEach-Object {\n \"$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))\"\n }) -join \"&\"\n $url = \"$url?$query\"\n }\n $headers = @{\n \"x-auth-token\" = $ACCESS_TOKEN\n \"x-client-id\" = $CLIENT_ID\n }\n\n Invoke-RestMethod -Method GET -Uri $url -Headers $headers\n}\n\n# Example usage\n# Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\n$params = @{ language = \"en\"; resource_id = \"58\"; include_resources = \"true\" }\n$data = Call-Api(\"1\", $params)\nWrite-Output $data"
},
{
"lang": "bash",
"label": "cURL",
"source": "# Get Chapter Info\n# Replace resource_id with the id or slug for a specific author such as Ibn Ashur.\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/chapters/1/info?language=en&resource_id=58&include_resources=true' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to get chapter info using the Quran Foundation API.\n\nEndpoint: GET /chapters/{id}/info\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \nPath Parameters:\n id: Chapter number (1-114) (e.g., \"1\")\nOptional Query Parameters:\n language: Language ISO code for translated metadata. Defaults to English.\n locale: Locale fallback if a language code is not provided.\n resource_id: Resource id or slug of the chapter info resource to fetch. Use this to request a specific author such as Ibn Ashur after discovering the identifier via /resources/chapter_infos or include_resources=true.\n include_resources: When true, include the ordered list of available chapter info resources for the resolved language.\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/chapters/{id}/info?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts id and optional parameters including resource_id and include_resources\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/hadith_references/by_ayah/{ayah_key}": {
"get": {
"tags": ["Hadith"],
"summary": "Get hadith references for a specific Ayah",
"description": "Get the ordered hadith reference records linked to a specific ayah.",
"operationId": "hadith-references-by-ayah",
"parameters": [
{
"name": "ayah_key",
"in": "path",
"description": "Ayah key in `chapter:verse` format, for example `12:12`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "language",
"in": "query",
"description": "Language ISO code used for the `language` and `direction` metadata fields in the response. Defaults to `en`.",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-references-by-ayah-response"
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verse_key": "12:12",
"verse_number": 12,
"chapter_number": 12,
"language": "en",
"direction": "ltr",
"hadith_references": [
{
"id": 10,
"collection": "bukhari",
"hadith_number": "1",
"our_hadith_number": 1,
"arabic_urn": 111,
"english_urn": 211,
"surah_number": 12,
"ayah_start_number": 11,
"ayah_end_number": 12
},
{
"id": 11,
"collection": "muslim",
"hadith_number": "3",
"our_hadith_number": 1,
"arabic_urn": 113,
"english_urn": 213,
"surah_number": 12,
"ayah_start_number": 12,
"ayah_end_number": 14
}
]
}
},
"references_found": {
"summary": "Ayah with hadith references",
"value": {
"verse_key": "12:12",
"verse_number": 12,
"chapter_number": 12,
"language": "en",
"direction": "ltr",
"hadith_references": [
{
"id": 10,
"collection": "bukhari",
"hadith_number": "1",
"our_hadith_number": 1,
"arabic_urn": 111,
"english_urn": 211,
"surah_number": 12,
"ayah_start_number": 11,
"ayah_end_number": 12
},
{
"id": 11,
"collection": "muslim",
"hadith_number": "3",
"our_hadith_number": 1,
"arabic_urn": 113,
"english_urn": 213,
"surah_number": 12,
"ayah_start_number": 12,
"ayah_end_number": 14
}
]
}
},
"no_references": {
"summary": "Ayah with no hadith references",
"value": {
"verse_key": "1:1",
"verse_number": 1,
"chapter_number": 1,
"language": "en",
"direction": "ltr",
"hadith_references": []
}
}
}
}
}
},
"400": {
"description": "Returned when `ayah_key` is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"invalid_request": {
"summary": "Invalid request",
"value": {
"status": 400,
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid ayah_key format. Expected format: chapter:verse (e.g., 12:12)",
"details": {
"parameter": "ayah_key",
"provided": "12-12",
"expected": "12:12"
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"description": "Returned when the ayah does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"not_found": {
"summary": "Resource not found",
"value": {
"status": 404,
"error": {
"code": "NOT_FOUND",
"message": "Verse 999:999 not found",
"details": {}
}
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
}
}
},
"/hadith_references/by_ayah/{ayah_key}/hadiths": {
"get": {
"tags": ["Hadith"],
"summary": "Get hadiths for a specific Ayah",
"description": "Get paginated hadith payloads for a specific ayah.",
"operationId": "hadiths-by-ayah",
"parameters": [
{
"name": "ayah_key",
"in": "path",
"description": "Ayah key in `chapter:verse` format, for example `12:12`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "language",
"in": "query",
"description": "Hadith language. Use `ar` for Arabic. Any non-`ar` value behaves like English and returns English hadith content.",
"schema": {
"type": "string",
"default": "en",
"example": "en"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for the hadith result set. Defaults to `1`.",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "limit",
"in": "query",
"description": "Number of hadith records per page. Defaults to `4` and is capped at `5`.",
"schema": {
"type": "integer",
"default": 4,
"minimum": 1,
"maximum": 5
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-by-ayah-response"
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"hadiths": [
{
"urn": 201,
"collection": "bukhari",
"bookNumber": "1",
"chapterId": "1",
"hadithNumber": "1",
"name": "Sahih al-Bukhari",
"hadith": [
{
"lang": "en",
"chapterNumber": "1",
"chapterTitle": "Revelation",
"body": "Narrated Umar bin Al-Khattab:...",
"urn": 31,
"grades": [
{
"graded_by": "Ahmad Muhammad Shakir",
"grade": "Sahih"
}
]
}
]
},
{
"urn": 202,
"collection": "muslim",
"bookNumber": "1",
"chapterId": "2",
"hadithNumber": "1",
"name": "Sahih Muslim",
"hadith": [
{
"lang": "en",
"chapterNumber": "2",
"chapterTitle": "Faith",
"body": "Narrated Abu Huraira:...",
"urn": 33,
"grades": []
}
]
}
],
"page": 1,
"limit": 4,
"has_more": true,
"language": "en",
"direction": "ltr"
}
},
"hadiths_found": {
"summary": "Hadith references expanded into hadith text",
"value": {
"hadiths": [
{
"urn": 201,
"collection": "bukhari",
"bookNumber": "1",
"chapterId": "1",
"hadithNumber": "1",
"name": "Sahih al-Bukhari",
"hadith": [
{
"lang": "en",
"chapterNumber": "1",
"chapterTitle": "Revelation",
"body": "Narrated Umar bin Al-Khattab:...",
"urn": 31,
"grades": [
{
"graded_by": "Ahmad Muhammad Shakir",
"grade": "Sahih"
}
]
}
]
},
{
"urn": 202,
"collection": "muslim",
"bookNumber": "1",
"chapterId": "2",
"hadithNumber": "1",
"name": "Sahih Muslim",
"hadith": [
{
"lang": "en",
"chapterNumber": "2",
"chapterTitle": "Faith",
"body": "Narrated Abu Huraira:...",
"urn": 33,
"grades": []
}
]
}
],
"page": 1,
"limit": 4,
"has_more": true,
"language": "en",
"direction": "ltr"
}
},
"no_hadiths": {
"summary": "No hadiths for the selected ayah",
"value": {
"hadiths": [],
"page": 1,
"limit": 4,
"has_more": false,
"language": "en",
"direction": "ltr"
}
}
}
}
}
},
"400": {
"description": "Returned when `ayah_key` is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"invalid_request": {
"summary": "Invalid request",
"value": {
"status": 400,
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid ayah_key format. Expected format: chapter:verse (e.g., 12:12)",
"details": {
"parameter": "ayah_key",
"provided": "12-12",
"expected": "12:12"
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"description": "Returned when the ayah does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"not_found": {
"summary": "Resource not found",
"value": {
"status": 404,
"error": {
"code": "NOT_FOUND",
"message": "Verse 999:999 not found",
"details": {}
}
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"description": "Returned when Sunnah API configuration is missing on the server.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"internal_server_error": {
"summary": "Internal server error",
"value": {
"status": 500,
"error": {
"code": "CONFIGURATION_ERROR",
"message": "SUNNAH_API_KEY is required",
"details": {}
}
}
}
}
}
}
},
"502": {
"description": "Returned when the upstream Sunnah service fails.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"bad_gateway": {
"summary": "Bad gateway",
"value": {
"status": 502,
"error": {
"code": "UPSTREAM_ERROR",
"message": "Too Many Requests.",
"details": {
"status": 429
}
}
}
}
}
}
}
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
}
}
},
"/hadith_references/count_within_range": {
"get": {
"tags": ["Hadith"],
"summary": "Get hadith counts within a verse range",
"description": "Get a map of verse keys to hadith counts within an inclusive ayah range. The optional `language` query parameter is accepted for parity with internal consumers, but the count response itself is language-independent.",
"operationId": "hadith-count-within-range",
"parameters": [
{
"name": "from",
"in": "query",
"description": "Starting ayah key in `chapter:verse` format.",
"required": true,
"schema": {
"type": "string",
"example": "12:12"
}
},
{
"name": "to",
"in": "query",
"description": "Ending ayah key in `chapter:verse` format.",
"required": true,
"schema": {
"type": "string",
"example": "12:13"
}
},
{
"name": "language",
"in": "query",
"description": "Optional language code. The response data is not language-dependent.",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-count-within-range-response"
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"12:12": 2,
"12:13": 2
}
},
"range_with_counts": {
"summary": "Hadith counts by ayah key",
"value": {
"12:12": 2,
"12:13": 2
}
},
"range_with_no_matches": {
"summary": "Verse range with no hadith references",
"value": {
"1:1": 0,
"1:2": 0
}
}
}
}
}
},
"400": {
"description": "Returned when the range parameters are missing, malformed, invalid, or reversed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/hadith-error-response"
},
"examples": {
"invalid_request": {
"summary": "Invalid request",
"value": {
"status": 400,
"error": {
"code": "INVALID_PARAMETER",
"message": "Missing required parameters: from and to",
"details": {
"required": ["from", "to"]
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
}
}
},
"/pages": {
"get": {
"tags": ["Pages"],
"summary": "List Pages",
"description": "Get all pages for the selected mushaf.",
"operationId": "list-pages",
"parameters": [
{
"name": "mushaf",
"in": "query",
"description": "Optional mushaf id. Defaults to the system default mushaf.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["pages"],
"properties": {
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Internal Mushaf page record id. Use `page_number` for Mushaf page navigation."
},
"page_number": {
"type": "integer",
"description": "Page number in the selected mushaf."
},
"verse_mapping": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"first_verse_id": {
"type": "integer"
},
"last_verse_id": {
"type": "integer"
},
"verses_count": {
"type": "integer"
}
}
}
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"pages": [
{
"id": 1,
"page_number": 507,
"verse_mapping": {
"47:1": "47:3"
},
"first_verse_id": 4787,
"last_verse_id": 4789,
"verses_count": 3
}
]
}
},
"first_mushaf_pages": {
"summary": "First pages in the default mushaf",
"value": {
"pages": [
{
"id": 1,
"page_number": 1,
"verse_mapping": {
"1": "1-7"
},
"first_verse_id": 1,
"last_verse_id": 7,
"verses_count": 7
},
{
"id": 2,
"page_number": 2,
"verse_mapping": {
"2": "1-5"
},
"first_verse_id": 8,
"last_verse_id": 12,
"verses_count": 5
}
]
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// List Pages\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/pages`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi({\"mushaf\":\"2\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "bash",
"label": "cURL",
"source": "# List Pages\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/pages?mushaf=2' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to list pages using the Quran Foundation API.\n\nEndpoint: GET /pages\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/pages\n2. Inject both required headers on every request\n3. Handle 401, 403, and 429 responses gracefully"
}
]
}
},
"/pages/lookup": {
"get": {
"tags": ["Pages"],
"summary": "Lookup Pages",
"description": "Get page boundaries for a chapter, juz, page, manzil, hizb, rub el hizb, ruku, or verse range in the selected mushaf.",
"operationId": "get-pages-lookup",
"parameters": [
{
"name": "mushaf",
"in": "query",
"description": "Optional mushaf id. Defaults to the system default mushaf.",
"schema": {
"type": "integer"
}
},
{
"name": "chapter_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "juz_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "page_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "manzil_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "rub_el_hizb_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "hizb_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "ruku_number",
"in": "query",
"schema": {
"type": "integer"
}
},
{
"name": "from",
"in": "query",
"description": "Starting verse key or verse id.",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "Ending verse key or verse id.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"total_page": {
"type": "integer"
},
"lookup_range": {
"type": "object",
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
}
}
},
"pages": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"first_verse_key": {
"type": "string"
},
"last_verse_key": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
}
}
}
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"total_page": 2,
"lookup_range": {
"from": "47:1",
"to": "47:5"
},
"pages": {
"507": {
"first_verse_key": "47:1",
"last_verse_key": "47:3",
"from": "47:1",
"to": "47:3"
},
"508": {
"first_verse_key": "47:4",
"last_verse_key": "47:5",
"from": "47:4",
"to": "47:5"
}
}
}
},
"ayah_range_spans_pages": {
"summary": "Ayah range split across multiple pages",
"value": {
"total_page": 2,
"lookup_range": {
"from": "47:1",
"to": "47:5"
},
"pages": {
"507": {
"first_verse_key": "47:1",
"last_verse_key": "47:3",
"from": "47:1",
"to": "47:3"
},
"508": {
"first_verse_key": "47:4",
"last_verse_key": "47:5",
"from": "47:4",
"to": "47:5"
}
}
}
},
"single_ayah_lookup": {
"summary": "Single ayah page lookup",
"value": {
"total_page": 1,
"lookup_range": {
"from": "2:255",
"to": "2:255"
},
"pages": {
"42": {
"first_verse_key": "2:253",
"last_verse_key": "2:256",
"from": "2:255",
"to": "2:255"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// Lookup Pages\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/pages/lookup`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi({\"mushaf\":\"2\",\"from\":\"47:1\",\"to\":\"47:5\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "bash",
"label": "cURL",
"source": "# Lookup Pages\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/pages/lookup?mushaf=2&from=47%3A1&to=47%3A5' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to lookup pages using the Quran Foundation API.\n\nEndpoint: GET /pages/lookup\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/pages/lookup\n2. Inject both required headers on every request\n3. Handle 401, 403, and 429 responses gracefully"
}
]
}
},
"/pages/{page_number}": {
"get": {
"tags": ["Pages"],
"summary": "Get Page",
"description": "Get metadata for a single page in the selected mushaf.",
"operationId": "get-pages-page-number",
"parameters": [
{
"name": "page_number",
"in": "path",
"description": "Page number in the selected mushaf.",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"name": "mushaf",
"in": "query",
"description": "Optional mushaf id. Defaults to the system default mushaf.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["page"],
"properties": {
"page": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Internal Mushaf page record id. Use `page_number` for Mushaf page navigation."
},
"page_number": {
"type": "integer",
"description": "Page number in the selected mushaf."
},
"verse_mapping": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"first_verse_id": {
"type": "integer"
},
"last_verse_id": {
"type": "integer"
},
"verses_count": {
"type": "integer"
}
}
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"page": {
"id": 1,
"page_number": 507,
"verse_mapping": {
"47:1": "47:3"
},
"first_verse_id": 4787,
"last_verse_id": 4789,
"verses_count": 3
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// Get Page\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(page_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/pages/${page_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"507\", {\"mushaf\":\"2\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "bash",
"label": "cURL",
"source": "# Get Page\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/pages/507?mushaf=2' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to get page using the Quran Foundation API.\n\nEndpoint: GET /pages/{page_number}\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/pages/{page_number}\n2. Inject both required headers on every request\n3. Handle 401, 403, and 429 responses gracefully"
}
]
}
},
"/verses/by_chapter/{chapter_number}": {
"get": {
"tags": ["Verses"],
"summary": "By Chapter",
"description": "Get list of Verse(s) by Chapter / Surah number.",
"operationId": "verses-by_chapter_number",
"parameters": [
{
"name": "chapter_number",
"in": "path",
"description": "Chapter number ( 1 - 114 )",
"required": true,
"schema": {
"maximum": 114,
"minimum": 1,
"type": "integer"
}
},
{
"name": "language",
"in": "query",
"description": "Language to fetch word-by-word translation in a specific language.",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "words",
"in": "query",
"description": "Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
}
},
{
"name": "translations",
"in": "query",
"description": "comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.",
"schema": {
"type": "string"
}
},
{
"name": "audio",
"in": "query",
"description": "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.",
"schema": {
"type": "integer"
}
},
{
"name": "tafsirs",
"in": "query",
"description": "Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.",
"schema": {
"type": "string"
}
},
{
"name": "word_fields",
"in": "query",
"description": "Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields).",
"schema": {
"type": "string"
}
},
{
"name": "translation_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "tafsir_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "For paginating within the result",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "records per api call, you can get maximum 50 records. ",
"schema": {
"maximum": 50,
"minimum": 1,
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/verse"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verses": [
{
"id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"text": "In the Name of Allah—the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "Which was revealed in Makkah
The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
},
"compact_fields": {
"summary": "Compact verse fields for navigation views",
"value": {
"verses": [
{
"id": 255,
"chapter_id": 2,
"verse_number": 255,
"verse_key": "2:255",
"verse_index": 262,
"juz_number": 3,
"hizb_number": 5,
"rub_el_hizb_number": 19,
"page_number": 42
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1
}
}
},
"with_words_translation_tafsir_audio": {
"summary": "Verse payload with words, translation, tafsir, and audio",
"value": {
"verses": [
{
"id": 1,
"chapter_id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"audio": {
"verse_key": "1:1",
"url": "https://verses.quran.foundation/Alafasy/mp3/001001.mp3"
},
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"resource_name": "Dr. Mustafa Khattab, the Clear Quran",
"text": "In the Name of Allah?the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"resource_id": 169,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// By Chapter\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(chapter_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/verses/by_chapter/${chapter_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"1\", {\"language\":\"en\",\"words\":\"true\",\"translations\":\"131\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# By Chapter\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(chapter_number, language=None, words=None, translations=None):\n params = {k: v for k, v in {'language': language, 'words': words, 'translations': translations}.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/verses/by_chapter/{chapter_number}',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\ntry:\n data = call_api(\"1\", language=\"en\", words=\"true\", translations=\"131\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// By Chapter\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(chapter_number string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/verses/by_chapter/%s\", chapter_number)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"words\": \"true\", \"translations\": \"131\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# By Chapter\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(chapter_number, params = {})\n path = \"/verses/by_chapter/#{chapter_number}\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\nparams = { \"language\" => \"en\", \"words\" => \"true\", \"translations\" => \"131\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// By Chapter\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string chapter_number, Dictionary query = null)\n{\n var path = $@\"/verses/by_chapter/{chapter_number}\";\n var url = API_BASE_URL + path;\n if (query != null && query.Count > 0)\n {\n var queryString = string.Join(\"&\", query.Select(kvp =>\n $\"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}\"));\n url = $\"{url}?{queryString}\";\n }\n using var client = new HttpClient();\n using var request = new HttpRequestMessage(new HttpMethod(\"GET\"), url);\n request.Headers.Add(\"x-auth-token\", ACCESS_TOKEN);\n request.Headers.Add(\"x-client-id\", CLIENT_ID);\n\n using var response = await client.SendAsync(request);\n response.EnsureSuccessStatusCode();\n return await response.Content.ReadAsStringAsync();\n}\n\n// Example usage\nvar query = new Dictionary { {\"language\", \"en\"}, {\"words\", \"true\"}, {\"translations\", \"131\"} };\nvar data = await CallApiAsync(\"1\", query);\nConsole.WriteLine(data);"
},
{
"lang": "php",
"label": "PHP",
"source": "# By Chapter\n';\nconst CLIENT_ID = '';\n\nfunction callApi($chapter_number, $params = []) {\n $path = sprintf(\"/verses/by_chapter/%s\", $chapter_number);\n $url = API_BASE_URL . $path;\n if (!empty($params)) {\n $url .= '?' . http_build_query($params);\n }\n $ch = curl_init($url);\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');\n curl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'x-auth-token: ' . ACCESS_TOKEN,\n 'x-client-id: ' . CLIENT_ID\n ]);\n\n $response = curl_exec($ch);\n if ($response === false) {\n throw new Exception(curl_error($ch));\n }\n curl_close($ch);\n return $response;\n}\n\n// Example usage\n$params = ['language' => 'en', 'words' => 'true', 'translations' => '131'];\n$data = callApi(\"1\", $params);\necho $data;\n?>"
},
{
"lang": "java",
"label": "Java",
"source": "// By Chapter\nimport java.io.IOException;\nimport java.util.HashMap;\nimport java.util.Map;\nimport okhttp3.HttpUrl;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\n\npublic class Main {\n private static final String API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\n private static final String ACCESS_TOKEN = \"\";\n private static final String CLIENT_ID = \"\";\n\n public static String callApi(String chapter_number, Map params) throws IOException {\n String path = String.format(\"/verses/by_chapter/%s\", chapter_number);\n HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();\n if (params != null) {\n for (Map.Entry entry : params.entrySet()) {\n urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n String method = \"GET\";\n RequestBody requestBody = method.equals(\"GET\") ? null : RequestBody.create(new byte[0]);\n Request request = new Request.Builder()\n .url(urlBuilder.build())\n .addHeader(\"x-auth-token\", ACCESS_TOKEN)\n .addHeader(\"x-client-id\", CLIENT_ID)\n .method(method, requestBody)\n .build();\n\n OkHttpClient client = new OkHttpClient();\n Response response = client.newCall(request).execute();\n return response.body().string();\n }\n\n public static void main(String[] args) throws Exception {\n Map params = new HashMap<>();\n params.put(\"language\", \"en\");\n params.put(\"words\", \"true\");\n params.put(\"translations\", \"131\");\n String data = callApi(\"1\", params);\n System.out.println(data);\n }\n}"
},
{
"lang": "powershell",
"label": "PowerShell",
"source": "# By Chapter\n$API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\n$ACCESS_TOKEN = \"\"\n$CLIENT_ID = \"\"\n\nfunction Call-Api([string]$chapter_number, [hashtable]$params = @{}) {\n $path = \"/verses/by_chapter/$chapter_number\"\n $url = \"$API_BASE_URL$path\"\n if ($params.Count -gt 0) {\n $query = ($params.GetEnumerator() | ForEach-Object {\n \"$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))\"\n }) -join \"&\"\n $url = \"$url?$query\"\n }\n $headers = @{\n \"x-auth-token\" = $ACCESS_TOKEN\n \"x-client-id\" = $CLIENT_ID\n }\n\n Invoke-RestMethod -Method GET -Uri $url -Headers $headers\n}\n\n# Example usage\n$params = @{ language = \"en\"; words = \"true\"; translations = \"131\" }\n$data = Call-Api(\"1\", $params)\nWrite-Output $data"
},
{
"lang": "bash",
"label": "cURL",
"source": "# By Chapter\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/verses/by_chapter/1?language=en&words=true&translations=131' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to by chapter using the Quran Foundation API.\n\nEndpoint: GET /verses/by_chapter/{chapter_number}\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \nPath Parameters:\n chapter_number: Chapter number ( 1 - 114 ) (e.g., \"1\")\nOptional Query Parameters:\n language: Language to fetch word-by-word translation in a specific language.\n words: Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.\n translations: comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.\n audio: 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.\n tafsirs: Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/verses/by_chapter/{chapter_number}?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts chapter_number and optional parameters\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/verses/by_page/{page_number}": {
"get": {
"tags": ["Verses"],
"summary": "By Page",
"description": "Get all verses of a specific page in the selected mushaf.",
"operationId": "verses-by_page_number",
"parameters": [
{
"name": "page_number",
"in": "path",
"description": "Page number in the selected mushaf.",
"required": true,
"schema": {
"minimum": 1,
"type": "integer"
}
},
{
"name": "language",
"in": "query",
"description": "Language to fetch word-by-word translation in a specific language.",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "mushaf",
"in": "query",
"description": "Optional mushaf id. When provided, page boundaries and line layout are resolved from the selected mushaf.",
"schema": {
"type": "integer"
}
},
{
"name": "words",
"in": "query",
"description": "Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
}
},
{
"name": "translations",
"in": "query",
"description": "comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.",
"schema": {
"type": "string"
}
},
{
"name": "audio",
"in": "query",
"description": "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.",
"schema": {
"type": "integer"
}
},
{
"name": "tafsirs",
"in": "query",
"description": "Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.",
"schema": {
"type": "string"
}
},
{
"name": "word_fields",
"in": "query",
"description": "Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields).",
"schema": {
"type": "string"
}
},
{
"name": "translation_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "tafsir_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "For paginating within the result",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "records per api call, you can get maximum 50 records. ",
"schema": {
"maximum": 50,
"minimum": 1,
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/verse"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verses": [
{
"id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"text": "In the Name of Allah—the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "Which was revealed in Makkah
The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
},
"compact_fields": {
"summary": "Compact verse fields for navigation views",
"value": {
"verses": [
{
"id": 255,
"chapter_id": 2,
"verse_number": 255,
"verse_key": "2:255",
"verse_index": 262,
"juz_number": 3,
"hizb_number": 5,
"rub_el_hizb_number": 19,
"page_number": 42
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1
}
}
},
"with_words_translation_tafsir_audio": {
"summary": "Verse payload with words, translation, tafsir, and audio",
"value": {
"verses": [
{
"id": 1,
"chapter_id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"audio": {
"verse_key": "1:1",
"url": "https://verses.quran.foundation/Alafasy/mp3/001001.mp3"
},
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"resource_name": "Dr. Mustafa Khattab, the Clear Quran",
"text": "In the Name of Allah?the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"resource_id": 169,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// By Page\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(page_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/verses/by_page/${page_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"1\", {\"language\":\"en\",\"words\":\"true\",\"translations\":\"131\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# By Page\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(page_number, language=None, words=None, translations=None):\n params = {k: v for k, v in {'language': language, 'words': words, 'translations': translations}.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/verses/by_page/{page_number}',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\ntry:\n data = call_api(\"1\", language=\"en\", words=\"true\", translations=\"131\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// By Page\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(page_number string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/verses/by_page/%s\", page_number)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"words\": \"true\", \"translations\": \"131\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# By Page\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(page_number, params = {})\n path = \"/verses/by_page/#{page_number}\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\nparams = { \"language\" => \"en\", \"words\" => \"true\", \"translations\" => \"131\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// By Page\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string page_number, Dictionary query = null)\n{\n var path = $@\"/verses/by_page/{page_number}\";\n var url = API_BASE_URL + path;\n if (query != null && query.Count > 0)\n {\n var queryString = string.Join(\"&\", query.Select(kvp =>\n $\"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}\"));\n url = $\"{url}?{queryString}\";\n }\n using var client = new HttpClient();\n using var request = new HttpRequestMessage(new HttpMethod(\"GET\"), url);\n request.Headers.Add(\"x-auth-token\", ACCESS_TOKEN);\n request.Headers.Add(\"x-client-id\", CLIENT_ID);\n\n using var response = await client.SendAsync(request);\n response.EnsureSuccessStatusCode();\n return await response.Content.ReadAsStringAsync();\n}\n\n// Example usage\nvar query = new Dictionary { {\"language\", \"en\"}, {\"words\", \"true\"}, {\"translations\", \"131\"} };\nvar data = await CallApiAsync(\"1\", query);\nConsole.WriteLine(data);"
},
{
"lang": "php",
"label": "PHP",
"source": "# By Page\n';\nconst CLIENT_ID = '';\n\nfunction callApi($page_number, $params = []) {\n $path = sprintf(\"/verses/by_page/%s\", $page_number);\n $url = API_BASE_URL . $path;\n if (!empty($params)) {\n $url .= '?' . http_build_query($params);\n }\n $ch = curl_init($url);\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');\n curl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'x-auth-token: ' . ACCESS_TOKEN,\n 'x-client-id: ' . CLIENT_ID\n ]);\n\n $response = curl_exec($ch);\n if ($response === false) {\n throw new Exception(curl_error($ch));\n }\n curl_close($ch);\n return $response;\n}\n\n// Example usage\n$params = ['language' => 'en', 'words' => 'true', 'translations' => '131'];\n$data = callApi(\"1\", $params);\necho $data;\n?>"
},
{
"lang": "java",
"label": "Java",
"source": "// By Page\nimport java.io.IOException;\nimport java.util.HashMap;\nimport java.util.Map;\nimport okhttp3.HttpUrl;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\n\npublic class Main {\n private static final String API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\n private static final String ACCESS_TOKEN = \"\";\n private static final String CLIENT_ID = \"\";\n\n public static String callApi(String page_number, Map params) throws IOException {\n String path = String.format(\"/verses/by_page/%s\", page_number);\n HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();\n if (params != null) {\n for (Map.Entry entry : params.entrySet()) {\n urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n String method = \"GET\";\n RequestBody requestBody = method.equals(\"GET\") ? null : RequestBody.create(new byte[0]);\n Request request = new Request.Builder()\n .url(urlBuilder.build())\n .addHeader(\"x-auth-token\", ACCESS_TOKEN)\n .addHeader(\"x-client-id\", CLIENT_ID)\n .method(method, requestBody)\n .build();\n\n OkHttpClient client = new OkHttpClient();\n Response response = client.newCall(request).execute();\n return response.body().string();\n }\n\n public static void main(String[] args) throws Exception {\n Map params = new HashMap<>();\n params.put(\"language\", \"en\");\n params.put(\"words\", \"true\");\n params.put(\"translations\", \"131\");\n String data = callApi(\"1\", params);\n System.out.println(data);\n }\n}"
},
{
"lang": "powershell",
"label": "PowerShell",
"source": "# By Page\n$API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\n$ACCESS_TOKEN = \"\"\n$CLIENT_ID = \"\"\n\nfunction Call-Api([string]$page_number, [hashtable]$params = @{}) {\n $path = \"/verses/by_page/$page_number\"\n $url = \"$API_BASE_URL$path\"\n if ($params.Count -gt 0) {\n $query = ($params.GetEnumerator() | ForEach-Object {\n \"$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))\"\n }) -join \"&\"\n $url = \"$url?$query\"\n }\n $headers = @{\n \"x-auth-token\" = $ACCESS_TOKEN\n \"x-client-id\" = $CLIENT_ID\n }\n\n Invoke-RestMethod -Method GET -Uri $url -Headers $headers\n}\n\n# Example usage\n$params = @{ language = \"en\"; words = \"true\"; translations = \"131\" }\n$data = Call-Api(\"1\", $params)\nWrite-Output $data"
},
{
"lang": "bash",
"label": "cURL",
"source": "# By Page\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/verses/by_page/1?language=en&words=true&translations=131' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to by page using the Quran Foundation API.\n\nEndpoint: GET /verses/by_page/{page_number}\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \nPath Parameters:\n page_number: Page number in the selected mushaf (e.g., \"1\")\nOptional Query Parameters:\n language: Language to fetch word-by-word translation in a specific language.\n mushaf: Optional mushaf id. When provided, page boundaries and line layout are resolved from the selected mushaf.\n words: Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.\n translations: comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.\n audio: 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.\n tafsirs: Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/verses/by_page/{page_number}?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts page_number and optional parameters\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/verses/by_juz/{juz_number}": {
"get": {
"tags": ["Verses"],
"summary": "By Juz",
"description": "Get all verses from a specific juz(1-30).",
"operationId": "verses-by_juz_number",
"parameters": [
{
"name": "juz_number",
"in": "path",
"required": true,
"schema": {
"maximum": 30,
"minimum": 1,
"type": "integer"
}
},
{
"name": "language",
"in": "query",
"description": "Language to fetch word-by-word translation in a specific language.",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "words",
"in": "query",
"description": "Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
}
},
{
"name": "translations",
"in": "query",
"description": "comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.",
"schema": {
"type": "string"
}
},
{
"name": "audio",
"in": "query",
"description": "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.",
"schema": {
"type": "integer"
}
},
{
"name": "tafsirs",
"in": "query",
"description": "Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.",
"schema": {
"type": "string"
}
},
{
"name": "word_fields",
"in": "query",
"description": "Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields).",
"schema": {
"type": "string"
}
},
{
"name": "translation_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "tafsir_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "For paginating within the result",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "records per api call, you can get maximum 50 records. ",
"schema": {
"maximum": 50,
"minimum": 1,
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/verse"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verses": [
{
"id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"text": "In the Name of Allah—the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "Which was revealed in Makkah
The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
},
"compact_fields": {
"summary": "Compact verse fields for navigation views",
"value": {
"verses": [
{
"id": 255,
"chapter_id": 2,
"verse_number": 255,
"verse_key": "2:255",
"verse_index": 262,
"juz_number": 3,
"hizb_number": 5,
"rub_el_hizb_number": 19,
"page_number": 42
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1
}
}
},
"with_words_translation_tafsir_audio": {
"summary": "Verse payload with words, translation, tafsir, and audio",
"value": {
"verses": [
{
"id": 1,
"chapter_id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"audio": {
"verse_key": "1:1",
"url": "https://verses.quran.foundation/Alafasy/mp3/001001.mp3"
},
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"resource_name": "Dr. Mustafa Khattab, the Clear Quran",
"text": "In the Name of Allah?the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"resource_id": 169,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// By Juz\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(juz_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/verses/by_juz/${juz_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"1\", {\"language\":\"en\",\"words\":\"true\",\"translations\":\"131\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# By Juz\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(juz_number, language=None, words=None, translations=None):\n params = {k: v for k, v in {'language': language, 'words': words, 'translations': translations}.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/verses/by_juz/{juz_number}',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\ntry:\n data = call_api(\"1\", language=\"en\", words=\"true\", translations=\"131\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// By Juz\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(juz_number string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/verses/by_juz/%s\", juz_number)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"words\": \"true\", \"translations\": \"131\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# By Juz\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(juz_number, params = {})\n path = \"/verses/by_juz/#{juz_number}\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\nparams = { \"language\" => \"en\", \"words\" => \"true\", \"translations\" => \"131\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// By Juz\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string juz_number, Dictionary query = null)\n{\n var path = $@\"/verses/by_juz/{juz_number}\";\n var url = API_BASE_URL + path;\n if (query != null && query.Count > 0)\n {\n var queryString = string.Join(\"&\", query.Select(kvp =>\n $\"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}\"));\n url = $\"{url}?{queryString}\";\n }\n using var client = new HttpClient();\n using var request = new HttpRequestMessage(new HttpMethod(\"GET\"), url);\n request.Headers.Add(\"x-auth-token\", ACCESS_TOKEN);\n request.Headers.Add(\"x-client-id\", CLIENT_ID);\n\n using var response = await client.SendAsync(request);\n response.EnsureSuccessStatusCode();\n return await response.Content.ReadAsStringAsync();\n}\n\n// Example usage\nvar query = new Dictionary { {\"language\", \"en\"}, {\"words\", \"true\"}, {\"translations\", \"131\"} };\nvar data = await CallApiAsync(\"1\", query);\nConsole.WriteLine(data);"
},
{
"lang": "php",
"label": "PHP",
"source": "# By Juz\n';\nconst CLIENT_ID = '';\n\nfunction callApi($juz_number, $params = []) {\n $path = sprintf(\"/verses/by_juz/%s\", $juz_number);\n $url = API_BASE_URL . $path;\n if (!empty($params)) {\n $url .= '?' . http_build_query($params);\n }\n $ch = curl_init($url);\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');\n curl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'x-auth-token: ' . ACCESS_TOKEN,\n 'x-client-id: ' . CLIENT_ID\n ]);\n\n $response = curl_exec($ch);\n if ($response === false) {\n throw new Exception(curl_error($ch));\n }\n curl_close($ch);\n return $response;\n}\n\n// Example usage\n$params = ['language' => 'en', 'words' => 'true', 'translations' => '131'];\n$data = callApi(\"1\", $params);\necho $data;\n?>"
},
{
"lang": "java",
"label": "Java",
"source": "// By Juz\nimport java.io.IOException;\nimport java.util.HashMap;\nimport java.util.Map;\nimport okhttp3.HttpUrl;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\n\npublic class Main {\n private static final String API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\n private static final String ACCESS_TOKEN = \"\";\n private static final String CLIENT_ID = \"\";\n\n public static String callApi(String juz_number, Map params) throws IOException {\n String path = String.format(\"/verses/by_juz/%s\", juz_number);\n HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();\n if (params != null) {\n for (Map.Entry entry : params.entrySet()) {\n urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n String method = \"GET\";\n RequestBody requestBody = method.equals(\"GET\") ? null : RequestBody.create(new byte[0]);\n Request request = new Request.Builder()\n .url(urlBuilder.build())\n .addHeader(\"x-auth-token\", ACCESS_TOKEN)\n .addHeader(\"x-client-id\", CLIENT_ID)\n .method(method, requestBody)\n .build();\n\n OkHttpClient client = new OkHttpClient();\n Response response = client.newCall(request).execute();\n return response.body().string();\n }\n\n public static void main(String[] args) throws Exception {\n Map params = new HashMap<>();\n params.put(\"language\", \"en\");\n params.put(\"words\", \"true\");\n params.put(\"translations\", \"131\");\n String data = callApi(\"1\", params);\n System.out.println(data);\n }\n}"
},
{
"lang": "powershell",
"label": "PowerShell",
"source": "# By Juz\n$API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\n$ACCESS_TOKEN = \"\"\n$CLIENT_ID = \"\"\n\nfunction Call-Api([string]$juz_number, [hashtable]$params = @{}) {\n $path = \"/verses/by_juz/$juz_number\"\n $url = \"$API_BASE_URL$path\"\n if ($params.Count -gt 0) {\n $query = ($params.GetEnumerator() | ForEach-Object {\n \"$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))\"\n }) -join \"&\"\n $url = \"$url?$query\"\n }\n $headers = @{\n \"x-auth-token\" = $ACCESS_TOKEN\n \"x-client-id\" = $CLIENT_ID\n }\n\n Invoke-RestMethod -Method GET -Uri $url -Headers $headers\n}\n\n# Example usage\n$params = @{ language = \"en\"; words = \"true\"; translations = \"131\" }\n$data = Call-Api(\"1\", $params)\nWrite-Output $data"
},
{
"lang": "bash",
"label": "cURL",
"source": "# By Juz\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/verses/by_juz/1?language=en&words=true&translations=131' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to by juz using the Quran Foundation API.\n\nEndpoint: GET /verses/by_juz/{juz_number}\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \nPath Parameters:\n juz_number: Required parameter (e.g., \"1\")\nOptional Query Parameters:\n language: Language to fetch word-by-word translation in a specific language.\n words: Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.\n translations: comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.\n audio: 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.\n tafsirs: Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/verses/by_juz/{juz_number}?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts juz_number and optional parameters\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/verses/by_hizb/{hizb_number}": {
"get": {
"tags": ["Verses"],
"summary": "By Hizb number",
"description": "Get all verses from a specific Hizb( half(1-60).",
"operationId": "verses-by_hizb_number",
"parameters": [
{
"name": "hizb_number",
"in": "path",
"description": "Hizb number(1-60)",
"required": true,
"schema": {
"maximum": 60,
"minimum": 1,
"type": "integer"
}
},
{
"name": "language",
"in": "query",
"description": "Language to fetch word-by-word translation in a specific language.",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "words",
"in": "query",
"description": "Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
}
},
{
"name": "translations",
"in": "query",
"description": "comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.",
"schema": {
"type": "string"
}
},
{
"name": "audio",
"in": "query",
"description": "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.",
"schema": {
"type": "integer"
}
},
{
"name": "tafsirs",
"in": "query",
"description": "Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.",
"schema": {
"type": "string"
}
},
{
"name": "word_fields",
"in": "query",
"description": "Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields).",
"schema": {
"type": "string"
}
},
{
"name": "translation_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "tafsir_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "For paginating within the result",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "records per api call, you can get maximum 50 records. ",
"schema": {
"maximum": 50,
"minimum": 1,
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/verse"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verses": [
{
"id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"text": "In the Name of Allah—the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "Which was revealed in Makkah
The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
},
"compact_fields": {
"summary": "Compact verse fields for navigation views",
"value": {
"verses": [
{
"id": 255,
"chapter_id": 2,
"verse_number": 255,
"verse_key": "2:255",
"verse_index": 262,
"juz_number": 3,
"hizb_number": 5,
"rub_el_hizb_number": 19,
"page_number": 42
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1
}
}
},
"with_words_translation_tafsir_audio": {
"summary": "Verse payload with words, translation, tafsir, and audio",
"value": {
"verses": [
{
"id": 1,
"chapter_id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"audio": {
"verse_key": "1:1",
"url": "https://verses.quran.foundation/Alafasy/mp3/001001.mp3"
},
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"resource_name": "Dr. Mustafa Khattab, the Clear Quran",
"text": "In the Name of Allah?the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"resource_id": 169,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// By Hizb number\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(hizb_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/verses/by_hizb/${hizb_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"1\", {\"language\":\"en\",\"words\":\"true\",\"translations\":\"131\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# By Hizb number\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(hizb_number, language=None, words=None, translations=None):\n params = {k: v for k, v in {'language': language, 'words': words, 'translations': translations}.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/verses/by_hizb/{hizb_number}',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\ntry:\n data = call_api(\"1\", language=\"en\", words=\"true\", translations=\"131\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// By Hizb number\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(hizb_number string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/verses/by_hizb/%s\", hizb_number)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"words\": \"true\", \"translations\": \"131\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# By Hizb number\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(hizb_number, params = {})\n path = \"/verses/by_hizb/#{hizb_number}\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\nparams = { \"language\" => \"en\", \"words\" => \"true\", \"translations\" => \"131\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// By Hizb number\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string hizb_number, Dictionary query = null)\n{\n var path = $@\"/verses/by_hizb/{hizb_number}\";\n var url = API_BASE_URL + path;\n if (query != null && query.Count > 0)\n {\n var queryString = string.Join(\"&\", query.Select(kvp =>\n $\"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}\"));\n url = $\"{url}?{queryString}\";\n }\n using var client = new HttpClient();\n using var request = new HttpRequestMessage(new HttpMethod(\"GET\"), url);\n request.Headers.Add(\"x-auth-token\", ACCESS_TOKEN);\n request.Headers.Add(\"x-client-id\", CLIENT_ID);\n\n using var response = await client.SendAsync(request);\n response.EnsureSuccessStatusCode();\n return await response.Content.ReadAsStringAsync();\n}\n\n// Example usage\nvar query = new Dictionary { {\"language\", \"en\"}, {\"words\", \"true\"}, {\"translations\", \"131\"} };\nvar data = await CallApiAsync(\"1\", query);\nConsole.WriteLine(data);"
},
{
"lang": "php",
"label": "PHP",
"source": "# By Hizb number\n';\nconst CLIENT_ID = '';\n\nfunction callApi($hizb_number, $params = []) {\n $path = sprintf(\"/verses/by_hizb/%s\", $hizb_number);\n $url = API_BASE_URL . $path;\n if (!empty($params)) {\n $url .= '?' . http_build_query($params);\n }\n $ch = curl_init($url);\n curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');\n curl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'x-auth-token: ' . ACCESS_TOKEN,\n 'x-client-id: ' . CLIENT_ID\n ]);\n\n $response = curl_exec($ch);\n if ($response === false) {\n throw new Exception(curl_error($ch));\n }\n curl_close($ch);\n return $response;\n}\n\n// Example usage\n$params = ['language' => 'en', 'words' => 'true', 'translations' => '131'];\n$data = callApi(\"1\", $params);\necho $data;\n?>"
},
{
"lang": "java",
"label": "Java",
"source": "// By Hizb number\nimport java.io.IOException;\nimport java.util.HashMap;\nimport java.util.Map;\nimport okhttp3.HttpUrl;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\n\npublic class Main {\n private static final String API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\n private static final String ACCESS_TOKEN = \"\";\n private static final String CLIENT_ID = \"\";\n\n public static String callApi(String hizb_number, Map params) throws IOException {\n String path = String.format(\"/verses/by_hizb/%s\", hizb_number);\n HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();\n if (params != null) {\n for (Map.Entry entry : params.entrySet()) {\n urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n String method = \"GET\";\n RequestBody requestBody = method.equals(\"GET\") ? null : RequestBody.create(new byte[0]);\n Request request = new Request.Builder()\n .url(urlBuilder.build())\n .addHeader(\"x-auth-token\", ACCESS_TOKEN)\n .addHeader(\"x-client-id\", CLIENT_ID)\n .method(method, requestBody)\n .build();\n\n OkHttpClient client = new OkHttpClient();\n Response response = client.newCall(request).execute();\n return response.body().string();\n }\n\n public static void main(String[] args) throws Exception {\n Map params = new HashMap<>();\n params.put(\"language\", \"en\");\n params.put(\"words\", \"true\");\n params.put(\"translations\", \"131\");\n String data = callApi(\"1\", params);\n System.out.println(data);\n }\n}"
},
{
"lang": "powershell",
"label": "PowerShell",
"source": "# By Hizb number\n$API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\n$ACCESS_TOKEN = \"\"\n$CLIENT_ID = \"\"\n\nfunction Call-Api([string]$hizb_number, [hashtable]$params = @{}) {\n $path = \"/verses/by_hizb/$hizb_number\"\n $url = \"$API_BASE_URL$path\"\n if ($params.Count -gt 0) {\n $query = ($params.GetEnumerator() | ForEach-Object {\n \"$($_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))\"\n }) -join \"&\"\n $url = \"$url?$query\"\n }\n $headers = @{\n \"x-auth-token\" = $ACCESS_TOKEN\n \"x-client-id\" = $CLIENT_ID\n }\n\n Invoke-RestMethod -Method GET -Uri $url -Headers $headers\n}\n\n# Example usage\n$params = @{ language = \"en\"; words = \"true\"; translations = \"131\" }\n$data = Call-Api(\"1\", $params)\nWrite-Output $data"
},
{
"lang": "bash",
"label": "cURL",
"source": "# By Hizb number\ncurl -X GET \\\n 'https://apis.quran.foundation/content/api/v4/verses/by_hizb/1?language=en&words=true&translations=131' \\\n -H 'x-auth-token: ' \\\n -H 'x-client-id: '"
},
{
"lang": "text",
"label": "🤖 AI Prompt",
"source": "Implement a function to by hizb number using the Quran Foundation API.\n\nEndpoint: GET /verses/by_hizb/{hizb_number}\nBase URL: https://apis.quran.foundation/content/api/v4\n\nRequired Headers (copy exactly):\n x-auth-token: \n x-client-id: \nPath Parameters:\n hizb_number: Hizb number(1-60) (e.g., \"1\")\nOptional Query Parameters:\n language: Language to fetch word-by-word translation in a specific language.\n words: Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.\n translations: comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.\n audio: 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.\n tafsirs: Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.\n\nImplementation Requirements:\n1. Build the request URL: {baseUrl}/verses/by_hizb/{hizb_number}?{queryParams}\n2. Inject both required headers on every request\n3. Handle errors safely:\n - 401: Token expired → re-request token and retry once\n - 403: Access denied → check client credentials\n - 429: Rate limited → implement exponential backoff\n\nAcceptance Checklist:\n- [ ] Function accepts hizb_number and optional parameters\n- [ ] Headers x-auth-token and x-client-id are sent\n- [ ] 401/403/429 errors are handled gracefully"
}
]
}
},
"/verses/by_rub/{rub_el_hizb_number}": {
"get": {
"tags": ["Verses"],
"summary": "By Rub el Hizb number",
"description": "Get all verses of a specific Rub el Hizb number(1-240).",
"operationId": "verses-by_rub_el_hizb_number",
"parameters": [
{
"name": "rub_el_hizb_number",
"in": "path",
"description": "Rub el Hizb number(1-240)",
"required": true,
"schema": {
"maximum": 240,
"minimum": 1,
"type": "integer"
}
},
{
"name": "language",
"in": "query",
"description": "Language to fetch word-by-word translation in a specific language.",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "words",
"in": "query",
"description": "Include words of each ayah? Use this to fetch word-by-word translation and transliteration.\n\n0 or false will not include words.\n\n1 or true will include the words.\n\nDefault is false.",
"schema": {
"type": "string",
"default": "false",
"enum": ["true", "false"]
}
},
{
"name": "translations",
"in": "query",
"description": "comma separated ids of translations to load for each ayah. See [/resources/translations](/docs/content_apis_versioned/translations) for available ids. Use translations=57 to include full-ayah transliteration.",
"schema": {
"type": "string"
}
},
{
"name": "audio",
"in": "query",
"description": "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.",
"schema": {
"type": "integer"
}
},
{
"name": "tafsirs",
"in": "query",
"description": "Comma separated ids of tafsirs to load for each ayah if you want to load tafsirs. See [/resources/tafsirs](/docs/content_apis_versioned/tafsirs) for available ids.",
"schema": {
"type": "string"
}
},
{
"name": "word_fields",
"in": "query",
"description": "Comma-separated list of word-level fields to include in response. [See full field reference](/docs/api/field-reference#word-level-fields).",
"schema": {
"type": "string"
}
},
{
"name": "translation_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "tafsir_fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "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).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/verse"
}
},
"pagination": {
"$ref": "#/components/schemas/pagination"
}
}
},
"examples": {
"default_success": {
"summary": "Successful response",
"value": {
"verses": [
{
"id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"text": "In the Name of Allah—the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "Which was revealed in Makkah
The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
},
"compact_fields": {
"summary": "Compact verse fields for navigation views",
"value": {
"verses": [
{
"id": 255,
"chapter_id": 2,
"verse_number": 255,
"verse_key": "2:255",
"verse_index": 262,
"juz_number": 3,
"hizb_number": 5,
"rub_el_hizb_number": 19,
"page_number": 42
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1
}
}
},
"with_words_translation_tafsir_audio": {
"summary": "Verse payload with words, translation, tafsir, and audio",
"value": {
"verses": [
{
"id": 1,
"chapter_id": 1,
"verse_number": 1,
"page_number": 1,
"verse_key": "1:1",
"juz_number": 1,
"hizb_number": 1,
"rub_el_hizb_number": 1,
"sajdah_type": null,
"sajdah_number": null,
"audio": {
"verse_key": "1:1",
"url": "https://verses.quran.foundation/Alafasy/mp3/001001.mp3"
},
"words": [
{
"id": 1,
"position": 1,
"audio_url": "wbw/001_001_001.mp3",
"char_type_name": "word",
"line_number": 2,
"page_number": 1,
"code_v1": "ﭑ",
"translation": {
"text": "In (the) name",
"language_name": "english"
},
"transliteration": {
"text": "bis'mi",
"language_name": "english"
}
}
],
"translations": [
{
"resource_id": 131,
"resource_name": "Dr. Mustafa Khattab, the Clear Quran",
"text": "In the Name of Allah?the Most Compassionate, Most Merciful."
}
],
"tafsirs": [
{
"id": 82641,
"resource_id": 169,
"language_name": "english",
"name": "Tafsir Ibn Kathir",
"text": "The Meaning of Al-Fatihah and its Various Names
"
}
]
}
],
"pagination": {
"per_page": 1,
"current_page": 1,
"next_page": 2,
"total_pages": 7,
"total_records": 7
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/invalidRequest"
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"403": {
"$ref": "#/components/responses/forbidden"
},
"404": {
"$ref": "#/components/responses/notFound"
},
"422": {
"$ref": "#/components/responses/unprocessableEntity"
},
"429": {
"$ref": "#/components/responses/rateLimitExceeded"
},
"500": {
"$ref": "#/components/responses/internalServerError"
},
"502": {
"$ref": "#/components/responses/badGateway"
},
"503": {
"$ref": "#/components/responses/serviceUnavailable"
},
"504": {
"$ref": "#/components/responses/gatewayTimeout"
}
},
"x-code-samples": [
{
"lang": "javascript",
"label": "Node.js",
"source": "// By Rub el Hizb number\nconst axios = require('axios');\n\nconst API_BASE_URL = 'https://apis.quran.foundation/content/api/v4';\nconst ACCESS_TOKEN = '';\nconst CLIENT_ID = '';\n\nasync function callApi(rub_el_hizb_number, options = {}) {\n const response = await axios.get(\n `${API_BASE_URL}/verses/by_rub/${rub_el_hizb_number}`,\n {\n headers: {\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params: options\n }\n );\n return response.data;\n}\n\n// Example usage\ncallApi(\"1\", {\"language\":\"en\",\"words\":\"true\",\"translations\":\"131\"})\n .then(data => console.log(data))\n .catch(err => console.error(err.response?.status, err.message));"
},
{
"lang": "python",
"label": "Python",
"source": "# By Rub el Hizb number\nimport requests\n\nAPI_BASE_URL = 'https://apis.quran.foundation/content/api/v4'\nACCESS_TOKEN = ''\nCLIENT_ID = ''\n\ndef call_api(rub_el_hizb_number, language=None, words=None, translations=None):\n params = {k: v for k, v in {'language': language, 'words': words, 'translations': translations}.items() if v is not None}\n \n response = requests.get(\n f'{API_BASE_URL}/verses/by_rub/{rub_el_hizb_number}',\n headers={\n 'x-auth-token': ACCESS_TOKEN,\n 'x-client-id': CLIENT_ID\n },\n params=params\n )\n response.raise_for_status()\n return response.json()\n\n# Example usage\ntry:\n data = call_api(\"1\", language=\"en\", words=\"true\", translations=\"131\")\n print(data)\nexcept requests.HTTPError as e:\n print(f'Error {e.response.status_code}: {e}')"
},
{
"lang": "go",
"label": "Go",
"source": "// By Rub el Hizb number\npackage main\n\nimport (\n \"fmt\"\n \"io\"\n \"net/http\"\n \"net/url\"\n)\n\nconst API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nconst ACCESS_TOKEN = \"\"\nconst CLIENT_ID = \"\"\n\nfunc callApi(rub_el_hizb_number string, params map[string]string) (string, error) {\n path := fmt.Sprintf(\"/verses/by_rub/%s\", rub_el_hizb_number)\n endpoint := API_BASE_URL + path\n if params != nil && len(params) > 0 {\n values := url.Values{}\n for k, v := range params {\n values.Set(k, v)\n }\n endpoint = endpoint + \"?\" + values.Encode()\n }\n\n req, err := http.NewRequest(\"GET\", endpoint, nil)\n if err != nil {\n return \"\", err\n }\n req.Header.Set(\"x-auth-token\", ACCESS_TOKEN)\n req.Header.Set(\"x-client-id\", CLIENT_ID)\n\n resp, err := http.DefaultClient.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n return string(body), nil\n}\n\n// Example usage\nfunc main() {\n params := map[string]string{\"language\": \"en\", \"words\": \"true\", \"translations\": \"131\"}\n data, err := callApi(\"1\", params)\n if err != nil {\n fmt.Println(\"Error:\", err)\n return\n }\n fmt.Println(data)\n}"
},
{
"lang": "ruby",
"label": "Ruby",
"source": "# By Rub el Hizb number\nrequire \"net/http\"\nrequire \"uri\"\n\nAPI_BASE_URL = \"https://apis.quran.foundation/content/api/v4\"\nACCESS_TOKEN = \"\"\nCLIENT_ID = \"\"\n\ndef call_api(rub_el_hizb_number, params = {})\n path = \"/verses/by_rub/#{rub_el_hizb_number}\"\n uri = URI(API_BASE_URL + path)\n uri.query = URI.encode_www_form(params) if params && !params.empty?\n request_class = Net::HTTP.const_get(\"Get\")\n request = request_class.new(uri)\n request[\"x-auth-token\"] = ACCESS_TOKEN\n request[\"x-client-id\"] = CLIENT_ID\n\n response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\n end\n\n response.body\nend\n\n# Example usage\nparams = { \"language\" => \"en\", \"words\" => \"true\", \"translations\" => \"131\" }\ndata = call_api(\"1\", params)\nputs data"
},
{
"lang": "csharp",
"label": "C#",
"source": "// By Rub el Hizb number\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nconst string API_BASE_URL = \"https://apis.quran.foundation/content/api/v4\";\nconst string ACCESS_TOKEN = \"\";\nconst string CLIENT_ID = \"\";\n\nstatic async Task CallApiAsync(string rub_el_hizb_number, Dictionary