|
Get list of available ayah-by-ayah recitations. Use these IDs with `/quran/recitations/{recitation_id}`, `/resources/recitations/{recitation_id}/info`, `/recitations/{recitation_id}/...`, and the `audio` query parameter on verse endpoints. These IDs are not interchangeable with chapter-reciter IDs from `/resources/chapter_reciters`. |
recitations |
| name |
in |
description |
schema |
language |
query |
Name of reciters in specific language. Will fallback to English if we don't have names in specific language. |
|
|
|
| 200 |
400 |
401 |
403 |
404 |
422 |
429 |
500 |
502 |
503 |
504 |
| description |
content |
Successful response |
| application/json |
| schema |
example |
| type |
required |
properties |
object |
|
| recitations |
| type |
items |
array |
| title |
type |
properties |
example |
Recitation |
object |
| id |
reciter_name |
style |
translated_name |
|
|
|
|
|
| id |
reciter_name |
style |
translated_name |
1 |
AbdulBaset AbdulSamad |
Mujawwad |
| name |
language_name |
AbdulBaset AbdulSamad |
english |
|
|
|
|
|
|
| recitations |
| id |
reciter_name |
style |
translated_name |
1 |
AbdulBaset AbdulSamad |
Mujawwad |
| name |
language_name |
AbdulBaset AbdulSamad |
english |
|
|
|
|
|
|
|
| description |
content |
Will be returned when the request is invalid e.g. request is missing required headers or with invalid query parameters. |
| application/json |
| schema |
example |
| title |
type |
properties |
invalidRequestResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The request is missing required headers or is invalid |
invalid_request |
false |
|
|
|
|
| description |
content |
Will be returned when the request is unauthorized. |
| application/json |
| schema |
example |
| title |
type |
properties |
unauthorizedResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The request requires user authentication |
unauthorized |
false |
|
|
|
|
| description |
content |
Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions. |
| application/json |
| schema |
example |
| title |
type |
properties |
forbiddenResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The server understood the request, but refuses to authorize it |
forbidden |
false |
|
|
|
|
| description |
content |
Not Found. The resource being accessed does not exist. |
| application/json |
| schema |
example |
| title |
type |
properties |
notFoundResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The requested resource could not be found |
not_found |
false |
|
|
|
|
| description |
content |
Validation Error. The request includes one or more invalid params. Please check the request params and try again. |
| application/json |
| schema |
example |
| title |
type |
properties |
unprocessableEntityResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The request was well-formed but was unable to be followed due to semantic errors |
unprocessable_entity |
false |
|
|
|
|
| description |
content |
Rate-limit exceeded |
| application/json |
| schema |
example |
| title |
type |
properties |
rateLimitExceededResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
Too many requests, please try again later |
rate_limit_exceeded |
false |
|
|
|
|
| description |
content |
Server Error. Something went wrong, try again later. |
| application/json |
| schema |
example |
| title |
type |
properties |
internalServerErrorResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The server encountered an internal error and was unable to complete your request |
internal_server_error |
false |
|
|
|
|
| description |
content |
Bad Gateway |
| application/json |
| schema |
example |
| title |
type |
properties |
badGatewayResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The server was acting as a gateway or proxy and received an invalid response from the upstream server |
bad_gateway |
false |
|
|
|
|
| description |
content |
Service Unavailable |
| application/json |
| schema |
example |
| title |
type |
properties |
serviceUnavailableResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The server is currently unable to handle the request due to a temporary overload or scheduled maintenance |
service_unavailable |
false |
|
|
|
|
| description |
content |
Gateway Timeout |
| application/json |
| schema |
example |
| title |
type |
properties |
gatewayTimeoutResponse |
object |
| message |
type |
success |
|
| type |
enum |
string |
gateway_timeout |
service_unavailable |
bad_gateway |
internal_server_error |
unprocessable_entity |
not_found |
forbidden |
unauthorized |
invalid_request |
invalid_token |
insufficient_scope |
service_error |
invalid_path |
rate_limit_exceeded |
|
|
|
|
|
| message |
type |
success |
The server was acting as a gateway or proxy and did not receive a timely response from the upstream server |
gateway_timeout |
false |
|
|
|
|
|
| lang |
label |
source |
javascript |
Node.js |
// Recitations
const axios = require('axios');
const API_BASE_URL = ' https://apis.quran.foundation/content/api/v4';
const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>';
const CLIENT_ID = '<YOUR_CLIENT_ID>';
async function callApi(options = {}) {
const response = await axios.get(
`${API_BASE_URL}/resources/recitations`,
{
headers: {
'x-auth-token': ACCESS_TOKEN,
'x-client-id': CLIENT_ID
},
params: options
}
);
return response.data;
}
// Example usage
callApi({"language":"en"})
.then(data => console.log(data))
.catch(err => console.error(err.response?.status, err.message)); |
|
| lang |
label |
source |
python |
Python |
# Recitations
import requests
API_BASE_URL = ' https://apis.quran.foundation/content/api/v4'
ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'
CLIENT_ID = '<YOUR_CLIENT_ID>'
def call_api(language=None):
params = {k: v for k, v in {'language': language}.items() if v is not None}
response = requests.get(
f'{API_BASE_URL}/resources/recitations',
headers={
'x-auth-token': ACCESS_TOKEN,
'x-client-id': CLIENT_ID
},
params=params
)
response.raise_for_status()
return response.json()
# Example usage
try:
data = call_api(language="en")
print(data)
except requests.HTTPError as e:
print(f'Error {e.response.status_code}: {e}') |
|
| lang |
label |
source |
go |
Go |
// Recitations
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
const API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
const ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
const CLIENT_ID = "<YOUR_CLIENT_ID>"
func callApi(params map[string]string) (string, error) {
path := "/resources/recitations"
endpoint := API_BASE_URL + path
if params != nil && len(params) > 0 {
values := url.Values{}
for k, v := range params {
values.Set(k, v)
}
endpoint = endpoint + "?" + values.Encode()
}
req, err := http.NewRequest("GET", endpoint, nil)
if err != nil {
return "", err
}
req.Header.Set("x-auth-token", ACCESS_TOKEN)
req.Header.Set("x-client-id", CLIENT_ID)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return "", err
}
return string(body), nil
}
// Example usage
func main() {
params := map[string]string{"language": "en"}
data, err := callApi(params)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println(data)
} |
|
| lang |
label |
source |
ruby |
Ruby |
# Recitations
require "net/http"
require "uri"
API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
CLIENT_ID = "<YOUR_CLIENT_ID>"
def call_api(params = {})
path = "/resources/recitations"
uri = URI(API_BASE_URL + path)
uri.query = URI.encode_www_form(params) if params && !params.empty?
request_class = Net::HTTP.const_get("Get")
request = request_class.new(uri)
request["x-auth-token"] = ACCESS_TOKEN
request["x-client-id"] = CLIENT_ID
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
response.body
end
# Example usage
params = { "language" => "en" }
data = call_api(params)
puts data |
|
| lang |
label |
source |
csharp |
C# |
// Recitations
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
const string API_BASE_URL = " https://apis.quran.foundation/content/api/v4";
const string ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>";
const string CLIENT_ID = "<YOUR_CLIENT_ID>";
static async Task<string> CallApiAsync(Dictionary<string, string> query = null)
{
var path = $@"/resources/recitations";
var url = API_BASE_URL + path;
if (query != null && query.Count > 0)
{
var queryString = string.Join("&", query.Select(kvp =>
$"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}"));
url = $"{url}?{queryString}";
}
using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), url);
request.Headers.Add("x-auth-token", ACCESS_TOKEN);
request.Headers.Add("x-client-id", CLIENT_ID);
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync();
}
// Example usage
var query = new Dictionary<string, string> { {"language", "en"} };
var data = await CallApiAsync(query);
Console.WriteLine(data); |
|
| lang |
label |
source |
php |
PHP |
# Recitations
<?php
const API_BASE_URL = ' https://apis.quran.foundation/content/api/v4';
const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>';
const CLIENT_ID = '<YOUR_CLIENT_ID>';
function callApi($params = []) {
$path = "/resources/recitations";
$url = API_BASE_URL . $path;
if (!empty($params)) {
$url .= '?' . http_build_query($params);
}
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-auth-token: ' . ACCESS_TOKEN,
'x-client-id: ' . CLIENT_ID
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
return $response;
}
// Example usage
$params = ['language' => 'en'];
$data = callApi($params);
echo $data;
?> |
|
| lang |
label |
source |
java |
Java |
// Recitations
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class Main {
private static final String API_BASE_URL = " https://apis.quran.foundation/content/api/v4";
private static final String ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>";
private static final String CLIENT_ID = "<YOUR_CLIENT_ID>";
public static String callApi(Map<String, String> params) throws IOException {
String path = "/resources/recitations";
HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();
if (params != null) {
for (Map.Entry<String, String> entry : params.entrySet()) {
urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());
}
}
String method = "GET";
RequestBody requestBody = method.equals("GET") ? null : RequestBody.create(new byte[0]);
Request request = new Request.Builder()
.url(urlBuilder.build())
.addHeader("x-auth-token", ACCESS_TOKEN)
.addHeader("x-client-id", CLIENT_ID)
.method(method, requestBody)
.build();
OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
return response.body().string();
}
public static void main(String[] args) throws Exception {
Map<String, String> params = new HashMap<>();
params.put("language", "en");
String data = callApi(params);
System.out.println(data);
}
} |
|
| lang |
label |
source |
powershell |
PowerShell |
# Recitations
$API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
$ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
$CLIENT_ID = "<YOUR_CLIENT_ID>"
function Call-Api([hashtable]$params = @{}) {
$path = "/resources/recitations"
$url = "$API_BASE_URL$path"
if ($params.Count -gt 0) {
$query = ( $params.GetEnumerator() | ForEach-Object {
"$( $_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))"
}) -join "&"
$url = "$url?$query"
}
$headers = @{
"x-auth-token" = $ACCESS_TOKEN
"x-client-id" = $CLIENT_ID
}
Invoke-RestMethod -Method GET -Uri $url -Headers $headers
}
# Example usage
$params = @{ language = "en" }
$data = Call-Api($params)
Write-Output $data |
|
| lang |
label |
source |
bash |
cURL |
|
|
| lang |
label |
source |
text |
🤖 AI Prompt |
Implement a function to recitations using the Quran Foundation API.
Endpoint: GET /resources/recitations
Base URL: https://apis.quran.foundation/content/api/v4
Required Headers (copy exactly):
x-auth-token: <YOUR_ACCESS_TOKEN>
x-client-id: <YOUR_CLIENT_ID>
Optional Query Parameters:
language: Name of reciters in specific language. Will fallback to English if we don't have names in specific language.
Notes:
This endpoint returns ayah-by-ayah recitation IDs.
Use these IDs with `/quran/recitations/{recitation_id}`, `/resources/recitations/{recitation_id}/info`, `/recitations/{recitation_id}/...`, and verse `audio` query parameters.
These IDs are not interchangeable with chapter-reciter IDs from `/resources/chapter_reciters`.
Implementation Requirements:
1. Build the request URL: {baseUrl}/resources/recitations?{queryParams}
2. Inject both required headers on every request
3. Handle errors safely:
- 401: Token expired → re-request token and retry once
- 403: Access denied → check client credentials
- 429: Rate limited → implement exponential backoff
Acceptance Checklist:
- [ ] Function accepts optional parameters
- [ ] Headers x-auth-token and x-client-id are sent
- [ ] 401/403/429 errors are handled gracefully |
|
|
| key |
value |
x-code-samples |
| lang |
label |
source |
javascript |
Node.js |
// Recitations
const axios = require('axios');
const API_BASE_URL = ' https://apis.quran.foundation/content/api/v4';
const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>';
const CLIENT_ID = '<YOUR_CLIENT_ID>';
async function callApi(options = {}) {
const response = await axios.get(
`${API_BASE_URL}/resources/recitations`,
{
headers: {
'x-auth-token': ACCESS_TOKEN,
'x-client-id': CLIENT_ID
},
params: options
}
);
return response.data;
}
// Example usage
callApi({"language":"en"})
.then(data => console.log(data))
.catch(err => console.error(err.response?.status, err.message)); |
|
| lang |
label |
source |
python |
Python |
# Recitations
import requests
API_BASE_URL = ' https://apis.quran.foundation/content/api/v4'
ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'
CLIENT_ID = '<YOUR_CLIENT_ID>'
def call_api(language=None):
params = {k: v for k, v in {'language': language}.items() if v is not None}
response = requests.get(
f'{API_BASE_URL}/resources/recitations',
headers={
'x-auth-token': ACCESS_TOKEN,
'x-client-id': CLIENT_ID
},
params=params
)
response.raise_for_status()
return response.json()
# Example usage
try:
data = call_api(language="en")
print(data)
except requests.HTTPError as e:
print(f'Error {e.response.status_code}: {e}') |
|
| lang |
label |
source |
go |
Go |
// Recitations
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
const API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
const ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
const CLIENT_ID = "<YOUR_CLIENT_ID>"
func callApi(params map[string]string) (string, error) {
path := "/resources/recitations"
endpoint := API_BASE_URL + path
if params != nil && len(params) > 0 {
values := url.Values{}
for k, v := range params {
values.Set(k, v)
}
endpoint = endpoint + "?" + values.Encode()
}
req, err := http.NewRequest("GET", endpoint, nil)
if err != nil {
return "", err
}
req.Header.Set("x-auth-token", ACCESS_TOKEN)
req.Header.Set("x-client-id", CLIENT_ID)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return "", err
}
return string(body), nil
}
// Example usage
func main() {
params := map[string]string{"language": "en"}
data, err := callApi(params)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println(data)
} |
|
| lang |
label |
source |
ruby |
Ruby |
# Recitations
require "net/http"
require "uri"
API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
CLIENT_ID = "<YOUR_CLIENT_ID>"
def call_api(params = {})
path = "/resources/recitations"
uri = URI(API_BASE_URL + path)
uri.query = URI.encode_www_form(params) if params && !params.empty?
request_class = Net::HTTP.const_get("Get")
request = request_class.new(uri)
request["x-auth-token"] = ACCESS_TOKEN
request["x-client-id"] = CLIENT_ID
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
response.body
end
# Example usage
params = { "language" => "en" }
data = call_api(params)
puts data |
|
| lang |
label |
source |
csharp |
C# |
// Recitations
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
const string API_BASE_URL = " https://apis.quran.foundation/content/api/v4";
const string ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>";
const string CLIENT_ID = "<YOUR_CLIENT_ID>";
static async Task<string> CallApiAsync(Dictionary<string, string> query = null)
{
var path = $@"/resources/recitations";
var url = API_BASE_URL + path;
if (query != null && query.Count > 0)
{
var queryString = string.Join("&", query.Select(kvp =>
$"{Uri.EscapeDataString(kvp.Key)}={Uri.EscapeDataString(kvp.Value)}"));
url = $"{url}?{queryString}";
}
using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), url);
request.Headers.Add("x-auth-token", ACCESS_TOKEN);
request.Headers.Add("x-client-id", CLIENT_ID);
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync();
}
// Example usage
var query = new Dictionary<string, string> { {"language", "en"} };
var data = await CallApiAsync(query);
Console.WriteLine(data); |
|
| lang |
label |
source |
php |
PHP |
# Recitations
<?php
const API_BASE_URL = ' https://apis.quran.foundation/content/api/v4';
const ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>';
const CLIENT_ID = '<YOUR_CLIENT_ID>';
function callApi($params = []) {
$path = "/resources/recitations";
$url = API_BASE_URL . $path;
if (!empty($params)) {
$url .= '?' . http_build_query($params);
}
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'x-auth-token: ' . ACCESS_TOKEN,
'x-client-id: ' . CLIENT_ID
]);
$response = curl_exec($ch);
if ($response === false) {
throw new Exception(curl_error($ch));
}
curl_close($ch);
return $response;
}
// Example usage
$params = ['language' => 'en'];
$data = callApi($params);
echo $data;
?> |
|
| lang |
label |
source |
java |
Java |
// Recitations
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class Main {
private static final String API_BASE_URL = " https://apis.quran.foundation/content/api/v4";
private static final String ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>";
private static final String CLIENT_ID = "<YOUR_CLIENT_ID>";
public static String callApi(Map<String, String> params) throws IOException {
String path = "/resources/recitations";
HttpUrl.Builder urlBuilder = HttpUrl.parse(API_BASE_URL + path).newBuilder();
if (params != null) {
for (Map.Entry<String, String> entry : params.entrySet()) {
urlBuilder.addQueryParameter(entry.getKey(), entry.getValue());
}
}
String method = "GET";
RequestBody requestBody = method.equals("GET") ? null : RequestBody.create(new byte[0]);
Request request = new Request.Builder()
.url(urlBuilder.build())
.addHeader("x-auth-token", ACCESS_TOKEN)
.addHeader("x-client-id", CLIENT_ID)
.method(method, requestBody)
.build();
OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
return response.body().string();
}
public static void main(String[] args) throws Exception {
Map<String, String> params = new HashMap<>();
params.put("language", "en");
String data = callApi(params);
System.out.println(data);
}
} |
|
| lang |
label |
source |
powershell |
PowerShell |
# Recitations
$API_BASE_URL = " https://apis.quran.foundation/content/api/v4"
$ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
$CLIENT_ID = "<YOUR_CLIENT_ID>"
function Call-Api([hashtable]$params = @{}) {
$path = "/resources/recitations"
$url = "$API_BASE_URL$path"
if ($params.Count -gt 0) {
$query = ( $params.GetEnumerator() | ForEach-Object {
"$( $_.Key)=$([System.Uri]::EscapeDataString([string]$_.Value))"
}) -join "&"
$url = "$url?$query"
}
$headers = @{
"x-auth-token" = $ACCESS_TOKEN
"x-client-id" = $CLIENT_ID
}
Invoke-RestMethod -Method GET -Uri $url -Headers $headers
}
# Example usage
$params = @{ language = "en" }
$data = Call-Api($params)
Write-Output $data |
|
| lang |
label |
source |
bash |
cURL |
|
|
| lang |
label |
source |
text |
🤖 AI Prompt |
Implement a function to recitations using the Quran Foundation API.
Endpoint: GET /resources/recitations
Base URL: https://apis.quran.foundation/content/api/v4
Required Headers (copy exactly):
x-auth-token: <YOUR_ACCESS_TOKEN>
x-client-id: <YOUR_CLIENT_ID>
Optional Query Parameters:
language: Name of reciters in specific language. Will fallback to English if we don't have names in specific language.
Notes:
This endpoint returns ayah-by-ayah recitation IDs.
Use these IDs with `/quran/recitations/{recitation_id}`, `/resources/recitations/{recitation_id}/info`, `/recitations/{recitation_id}/...`, and verse `audio` query parameters.
These IDs are not interchangeable with chapter-reciter IDs from `/resources/chapter_reciters`.
Implementation Requirements:
1. Build the request URL: {baseUrl}/resources/recitations?{queryParams}
2. Inject both required headers on every request
3. Handle errors safely:
- 401: Token expired → re-request token and retry once
- 403: Access denied → check client credentials
- 429: Rate limited → implement exponential backoff
Acceptance Checklist:
- [ ] Function accepts optional parameters
- [ ] Headers x-auth-token and x-client-id are sent
- [ ] 401/403/429 errors are handled gracefully |
|
|
|
|
get |
/resources/recitations |
| url |
description |
|
Pre-production Server |
|
| url |
description |
|
Production Server |
|
|
|
| x-auth-token |
x-client-id |
| type |
description |
name |
in |
apiKey |
The access token required for accessing the endpoints. |
x-auth-token |
header |
|
| type |
description |
name |
in |
apiKey |
Your client Id |
x-client-id |
header |
|
|
| title |
description |
version |
Content APIs |
Quran.Foundation Content APIs offer programmatic access to the Quran's core content like chapters, verses, recitations, translations, and more, distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).
:::important Integrity of Translations
Please **disable any automatic browser-translation features** (e.g. Google-Translate-in-Chrome) when displaying text returned by the *Translations* endpoints.
Re-translating an already vetted Quranic translation can introduce serious semantic errors.
:::
## How to get access
We are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Since the APIs are not user-related, you will need to use the `client_credentials` grant type and [`content` scope](/docs/user_related_apis_versioned/scopes#content) when sending a request to [The OAuth 2.0 Token Endpoint](/docs/oauth2_apis_versioned/oauth-2-token-exchange) to get the access token.
```mermaid
sequenceDiagram
participant App as Your App
participant Auth as Quran.Foundation<br/>Authorization Server
participant API as Quran.Foundation<br/>Resources Server
App->>Auth: Request Token with Client Credentials
Auth-->>App: Token Response (access_token)
App->>API: Use token to call API
API-->>App: Requested resource
Note over App,Auth: Access token expires (1 hour)
App->>Auth: Re-issue access_token using client_credentials
Auth-->>App: New access_token
```
After getting a valid access token, each request to get resources will have to include 2 headers mentioned below: `x-auth-token` and `x-client-id`. This spec also includes a small subset of Quran Reflect post-read endpoints that are compatible with the `client_credentials` grant. These operations still require `x-auth-token` and `x-client-id`, but they do not use the `content` scope. Use `post.read` for `/quran-reflect/v1/posts/feed`, `/quran-reflect/v1/posts/{id}`, and `/quran-reflect/v1/posts/user-posts/{id}`. Use `comment.read` for `/quran-reflect/v1/posts/{id}/comments` and `/quran-reflect/v1/posts/{id}/all-comments`. These are Quran Reflect gateway endpoints, not `/content/api/v4/...` endpoints. |
v4 |
|
| name |
description |
url |
header |
method |
Recitations |
| content |
type |
Get list of available ayah-by-ayah recitations. Use these IDs with `/quran/recitations/{recitation_id}`, `/resources/recitations/{recitation_id}/info`, `/recitations/{recitation_id}/...`, and the `audio` query parameter on verse endpoints. These IDs are not interchangeable with chapter-reciter IDs from `/resources/chapter_reciters`. |
text/plain |
|
| path |
host |
query |
variable |
|
|
| disabled |
description |
key |
value |
false |
| content |
type |
Name of reciters in specific language. Will fallback to English if we don't have names in specific language. |
text/plain |
|
language |
|
|
|
|
|
| key |
value |
Accept |
application/json |
|
|
GET |
|