Get hadith counts within a verse range

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.

Query Parameters

from string required

Starting ayah key in chapter:verse format.

to string required

Ending ayah key in chapter:verse format.

language string

Default value: en

Optional language code. The response data is not language-dependent.

Responses

• 200
• 400
• 401
• 403
• 429
• 500
• 502
• 503
• 504

---

Successful response

application/json

Schema

Example (from schema)

default_success

range_with_counts

range_with_no_matches

---

Schema

property name* integer

{
  "12:12": 2,
  "12:13": 2
}

Successful response

{
  "12:12": 2,
  "12:13": 2
}

Hadith counts by ayah key

{
  "12:12": 2,
  "12:13": 2
}

Verse range with no hadith references

{
  "1:1": 0,
  "1:2": 0
}

Returned when the range parameters are missing, malformed, invalid, or reversed.

application/json

Schema

Example (from schema)

invalid_request

---

Schema

status integer required
error object required
code string required
message string required
details object
property name* any

{
  "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": "Missing required parameters: from and to",
    "details": {
      "required": [
        "from",
        "to"
      ]
    }
  }
}

Will be returned when the request is unauthorized.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

Rate-limit exceeded

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "Too many requests, please try again later",
  "type": "rate_limit_exceeded",
  "success": false
}

Server Error. Something went wrong, try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

Bad Gateway

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

Service Unavailable

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "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

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

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]

success boolean

{
  "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
}

Loading...