Get hadiths for a specific Ayah
Get paginated hadith payloads for a specific ayah.
Path Parameters
Ayah key in chapter:verse format, for example 12:12.
Query Parameters
Default value: en
Hadith language. Use ar for Arabic. Any non-ar value behaves like English and returns English hadith content.
Possible values: >= 1
Default value: 1
Page number for the hadith result set. Defaults to 1.
Possible values: >= 1 and <= 5
Default value: 4
Number of hadith records per page. Defaults to 4 and is capped at 5.
- 200
- 400
- 401
- 403
- 404
- 429
- 500
- 502
- 503
- 504
Successful response
Schema
- Array [
- Array [
- Array [
- ]
- ]
- ]
hadiths object[] required
hadith object[] required
grades object[] required
{
"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"
}
]
}
]
}
],
"page": 0,
"limit": 0,
"has_more": true,
"language": "string",
"direction": "string"
}
Successful response
{
"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"
}
Hadith references expanded into hadith text
{
"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 for the selected ayah
{
"hadiths": [],
"page": 1,
"limit": 4,
"has_more": false,
"language": "en",
"direction": "ltr"
}
Returned when ayah_key is missing or invalid.
Schema
error object required
details object
{
"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"
}
}
}
Invalid request
{
"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"
}
}
}
Will be returned when the request is unauthorized.
Schema
Possible values: [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": "string",
"type": "gateway_timeout",
"success": true
}
{
"message": "The request requires user authentication",
"type": "unauthorized",
"success": false
}
Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions.
Schema
Possible values: [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": "string",
"type": "gateway_timeout",
"success": true
}
{
"message": "The server understood the request, but refuses to authorize it",
"type": "forbidden",
"success": false
}
Returned when the ayah does not exist.
Schema
error object required
details object
{
"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"
}
}
}
Resource not found
{
"status": 404,
"error": {
"code": "NOT_FOUND",
"message": "Verse 999:999 not found",
"details": {}
}
}
Rate-limit exceeded
Schema
Possible values: [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": "string",
"type": "gateway_timeout",
"success": true
}
{
"message": "Too many requests, please try again later",
"type": "rate_limit_exceeded",
"success": false
}
Returned when Sunnah API configuration is missing on the server.
Schema
error object required
details object
{
"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"
}
}
}
Internal server error
{
"status": 500,
"error": {
"code": "CONFIGURATION_ERROR",
"message": "SUNNAH_API_KEY is required",
"details": {}
}
}
Returned when the upstream Sunnah service fails.
Schema
error object required
details object
{
"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"
}
}
}
Bad gateway
{
"status": 502,
"error": {
"code": "UPSTREAM_ERROR",
"message": "Too Many Requests.",
"details": {
"status": 429
}
}
}
Service Unavailable
Schema
Possible values: [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": "string",
"type": "gateway_timeout",
"success": true
}
{
"message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
"type": "service_unavailable",
"success": false
}
Gateway Timeout
Schema
Possible values: [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": "string",
"type": "gateway_timeout",
"success": true
}
{
"message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
"type": "gateway_timeout",
"success": false
}