Get the Qira'at matrix for a chapter
Get the Qira'at matrix for a chapter: the approved junctures in the chapter with their readings and reader/transmitter attributions, paginated by juncture, together with all readers and transmitters. Unlike the by-verse matrix, readings here carry the translation but not explanations, and a chapter with no variations returns 200 with an empty junctures array. Requires the qiraat.read scope (or the parent qiraat scope); a token with only the content scope receives 403 with type: insufficient_scope. Qira'at endpoints are available in production only; they are not available in the prelive environment.
Path Parameters
Possible values: >= 1 and <= 114
Chapter (surah) number, from 1 to 114.
Query Parameters
Possible values: [text_uthmani, text_imlaei, text_qpc_hafs, uthmani, imlaei, qpc_hafs]
Default value: text_uthmani
Script used for verse, juncture, and reading text. The text_ prefix is optional (imlaei is the same as text_imlaei). Any other value resolves to text_uthmani.
Possible values: >= 1
Default value: 1
1-based page number. Defaults to 1.
Possible values: >= 1 and <= 100
Default value: 20
Number of junctures per page. Defaults to 20; values above 100 are capped at 100.
Default value: en
Language ISO code for translated names, translations, and explanations. Defaults to en. An unknown code resolves to en. Content that is missing in a language other than en or ar falls back to English; ar does not fall back.
- 200
- 401
- 403
- 404
- 429
- 500
- 502
- 503
- 504
Successful response
Schema
- Array [
- ]
- Array [
- ]
- Array [
- Array [
- Array [
- ]
- ]
- ]
chapter object required
readers object[] required
transmitters object[] required
junctures object[] required
Possible values: [A, B, C]
A meaning difference, B orthographic difference with the same meaning, C phonetic difference only.
readings object[] required
matrix object required
Attribution of the reading to the readers and transmitters axes.
Reader identifiers attributed to the reading.
Transmitter identifiers attributed to the reading.
cells object[] required
Possible values: [reader, transmitter]
pagination object required
meta object required
Possible values: [ltr, rtl]
{
"chapter": {
"id": 0,
"chapter_number": 0,
"name_simple": "string"
},
"readers": [
{
"id": 0,
"name": "string",
"abbreviation": "string",
"position": 0
}
],
"transmitters": [
{
"id": 0,
"name": "string",
"abbreviation": "string",
"reader_id": 0,
"position": 0,
"is_primary": true
}
],
"junctures": [
{
"id": 0,
"verse_key": "string",
"position": 0,
"word_id": 0,
"word_position": 0,
"start_word_position": 0,
"end_word_position": 0,
"text": "string",
"category": "A",
"readings": [
{
"id": 0,
"text": "string",
"text_uthmani": "string",
"text_imlaei": "string",
"translation": "string",
"matrix": {
"readers": [
0
],
"transmitters": [
0
],
"cells": [
{
"reader_id": 0,
"transmitter_id": 0,
"type": "reader"
}
]
}
}
]
}
],
"pagination": {
"current_page": 0,
"total_pages": 0,
"total_count": 0,
"per_page": 0
},
"meta": {
"language": "string",
"direction": "ltr",
"text_field": "string",
"generated_at": "2026-11-13T03:19:54.956Z"
}
}
Successful response
{
"chapter": {
"id": 1,
"chapter_number": 1,
"name_simple": "Al-Fatihah"
},
"readers": [
{
"id": 1,
"name": "Nafi",
"abbreviation": "N",
"position": 1
}
],
"transmitters": [
{
"id": 1,
"name": "Qalun",
"abbreviation": "Q",
"reader_id": 1,
"position": 1,
"is_primary": true
}
],
"junctures": [
{
"id": 10,
"verse_key": "1:4",
"position": 1,
"word_id": 24,
"word_position": 1,
"start_word_position": 1,
"end_word_position": 1,
"text": "...",
"category": "A",
"readings": [
{
"id": 20,
"text": "...",
"text_uthmani": "...",
"text_imlaei": "...",
"translation": "...",
"matrix": {
"readers": [
1
],
"transmitters": [
1
],
"cells": [
{
"reader_id": 1,
"transmitter_id": null,
"type": "reader"
},
{
"reader_id": 1,
"transmitter_id": 1,
"type": "transmitter"
}
]
}
}
]
}
],
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_count": 1,
"per_page": 20
},
"meta": {
"language": "en",
"direction": "ltr",
"text_field": "text_uthmani",
"generated_at": "2026-01-01T00:00:00Z"
}
}
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
}
The request is forbidden, for example because a valid access token lacks the required scope or the client lacks permission.
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
}
Not Found. Returned when the chapter does not exist.
Schema
details object required
The error body returned by the Qira'at service.
error object required
Possible values: [INVALID_PARAMETER, NOT_FOUND]
details object
Optional structured details, for example the offending parameter.
Optional structured details, for example the offending parameter.
Human-readable error message (the same text as details.error.message).
Possible values: [invalid_request, not_found]
{
"details": {
"status": 404,
"error": {
"code": "INVALID_PARAMETER",
"message": "string",
"details": {}
}
},
"message": "string",
"type": "invalid_request",
"success": false
}
{
"details": {
"status": 404,
"error": {
"code": "NOT_FOUND",
"message": "Chapter 999 not found"
}
},
"message": "Chapter 999 not found",
"type": "not_found",
"success": false
}
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
}
Server Error. Something went wrong, try again later.
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 encountered an internal error and was unable to complete your request",
"type": "internal_server_error",
"success": false
}
Bad Gateway
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 received an invalid response from the upstream server",
"type": "bad_gateway",
"success": false
}
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
}