Get Qur’an verses

Returns the Uthmani Arabic text of a verse, or of a range of up to 50 verses in one surah, with the surah name, juz and place of revelation. With locale en it adds an English translation. The text comes from the Quran Foundation API.

GET/quran/verses

Authorization

AuthorizationBearer token · headerrequired

An API key from qaf.ai Settings › API keys.

Query parameters

verseKeystringrequired

Surah and verse, like "2:255", or a range within one surah, like "2:255-257"; at most 50 verses.

min length 3 · max length 15

localestring

en adds an English translation and surah name; ar returns Arabic only.

default: "en"

Allowed:aren

Responses

200

The verses and their surah.

surahNamestringrequired

Surah name localized to the requested output language.

min length 1

surahNameArabicstringrequired

Canonical Arabic surah name.

min length 1

surahNumberintegerrequired

min 1 · max 114

verseStartintegerrequired

min 1

verseEndintegerrequired

min 1

verseTextstringrequired

Complete Arabic verse text without ornate brackets.

min length 1

translationstring | nullrequired

API-sourced translation in the output language when available.

Show properties

Any of:

string

string

null

null

juzintegerrequired

Juz containing the first verse in the requested range.

min 1 · max 30

revelationstringrequired

Allowed:makkimadaniunknown

401

The API key is missing, invalid or revoked.

codestringrequired

Allowed:UNAUTHORIZED

statusintegerrequired

messagestringrequired

403

The key's account can't use the API.

codestringrequired

Allowed:FORBIDDEN

statusintegerrequired

messagestringrequired

422

A field is invalid. data.fieldErrors lists the problems by field.

codestringrequired

Allowed:INPUT_VALIDATION_FAILED

statusintegerrequired

messagestringrequired

dataobject

Show properties

formErrorsstring[]required

fieldErrorsobjectrequired

429

Too many requests; data.reason says which limit was reached. For minute, the account's requests per minute, retry after Retry-After seconds. For day, the account's daily search cap, Retry-After is the time until the cap resets. For invalid_keys, the key doesn't exist or was revoked and this address has sent too many such keys, so fix the key rather than retrying. The X-RateLimit headers describe the account's minute window, so an invalid_keys refusal, which comes before any key is known, has none.

codestringrequired

Allowed:RATE_LIMITED

statusintegerrequired

messagestringrequired

dataobject

Show properties

retryAfterintegerrequired

Seconds to wait.

min 0

reasonstringrequired

Which limit was reached: minute, the account's requests per minute; day, its searches per day; or invalid_keys, a key that doesn't exist or was revoked, from an address that has sent too many such keys.

Allowed:minutedayinvalid_keys

500

Something went wrong on our side.

codestringrequired

Allowed:INTERNAL_SERVER_ERROR

statusintegerrequired

messagestringrequired

503

Qaf could not complete the request in time, or a service it relies on is unavailable. Retry shortly.

codestringrequired

Allowed:SERVICE_UNAVAILABLE

statusintegerrequired

messagestringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

verseKeyquery*Surah and verse, like "2:255", or a range within one surah, like "2:255-257"; at most 50 verses.localequeryen adds an English translation and surah name; ar returns Arabic only.

Request

curl -X GET 'https://api.qaf.ai/v1/quran/verses?verseKey=2%3A255' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response: Response = await fetch("https://api.qaf.ai/v1/quran/verses?verseKey=2%3A255", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.qaf.ai/v1/quran/verses?verseKey=2%3A255",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "surahName": "Al-Baqarah",
  "surahNameArabic": "البقرة",
  "surahNumber": 2,
  "verseStart": 255,
  "verseEnd": 255,
  "verseText": "ٱللَّهُ لَآ إِلَـٰهَ إِلَّا هُوَ ٱلْحَىُّ ٱلْقَيُّومُ ۚ لَا تَأْخُذُهُۥ سِنَةٌ وَلَا نَوْمٌ ۚ لَّهُۥ مَا فِى ٱلسَّمَـٰوَٰتِ وَمَا فِى ٱلْأَرْضِ ۗ مَن ذَا ٱلَّذِى يَشْفَعُ عِندَهُۥٓ إِلَّا بِإِذْنِهِۦ ۚ يَعْلَمُ مَا بَيْنَ أَيْدِيهِمْ وَمَا خَلْفَهُمْ ۖ وَلَا يُحِيطُونَ بِشَىْءٍ مِّنْ عِلْمِهِۦٓ إِلَّا بِمَا شَآءَ ۚ وَسِعَ كُرْسِيُّهُ ٱلسَّمَـٰوَٰتِ وَٱلْأَرْضَ ۖ وَلَا يَـُٔودُهُۥ حِفْظُهُمَا ۚ وَهُوَ ٱلْعَلِىُّ ٱلْعَظِيمُ",
  "translation": "Allāh - there is no deity except Him, the Ever-Living, the Self-Sustaining. Neither drowsiness overtakes Him nor sleep. To Him belongs whatever is in the heavens and whatever is on the earth. Who is it that can intercede with Him except by His permission? He knows what is [presently] before them and what will be after them, and they encompass not a thing of His knowledge except for what He wills. His Kursī extends over the heavens and the earth, and their preservation tires Him not. And He is the Most High, the Most Great.",
  "juz": 3,
  "revelation": "madani"
}

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Invalid API key."
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "This Qaf account can't use the API."
}

{
  "code": "INPUT_VALIDATION_FAILED",
  "status": 422,
  "message": "The request has invalid fields.",
  "data": {
    "formErrors": [
      "string"
    ],
    "fieldErrors": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "message": "Too many requests. Try again later.",
  "data": {
    "retryAfter": 0,
    "reason": "minute"
  }
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "message": "Something went wrong on our side. Try again later."
}

{
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "Qaf could not complete this request. Try again shortly."
}