Get hadith references for a specific Ayah

Get the ordered hadith reference records linked to a specific ayah.

Path Parameters

ayah_key string required

Ayah key in chapter:verse format, for example 12:12.

Query Parameters

language string

Default value: en

Language ISO code used for the language and direction metadata fields in the response. Defaults to en.

Responses

Successful response

application/json

Schema

Example (from schema)

default_success

references_found

no_references

Schema

verse_key string required

verse_number integer required

chapter_number integer required

language string required

direction string required

hadith_references object[] required

Array [

id integer required

collection string required

hadith_number string required

our_hadith_number integer required

arabic_urn integer required

english_urn integer required

surah_number integer required

ayah_start_number integer required

ayah_end_number integer required

]

{
  "verse_key": "string",
  "verse_number": 0,
  "chapter_number": 0,
  "language": "string",
  "direction": "string",
  "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
    }
  ]
}

Successful response

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

Ayah with hadith references

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

Ayah with no hadith references

{
  "verse_key": "1:1",
  "verse_number": 1,
  "chapter_number": 1,
  "language": "en",
  "direction": "ltr",
  "hadith_references": []
}

Returned when ayah_key is missing or invalid.

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

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

success boolean

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

application/json

Schema

Example (from schema)

not_found

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

Resource not found

{
  "status": 404,
  "error": {
    "code": "NOT_FOUND",
    "message": "Verse 999:999 not found",
    "details": {}
  }
}

Rate-limit exceeded

application/json

Schema

Example (from schema)

Example

Schema

message string

type string

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

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

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

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

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
}

Get hadith references for a specific Ayah​

Get hadith references for a specific Ayah