# Quran.com API

> Quran.com returns Quran verses and translations as a workflow and API.

Search quran finds verses by word or topic and returns Arabic text with translations in the selected language.

- Page: https://fous.com/tools/quran-com
- Handle: `@quran-com`
- Category: [Education](https://fous.com/tools/category/education)
- Source website: https://quran.com
- Last verified: Sep 29, 2026

## Methods

### Get verses

Operation `get_verses`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Read up to 50 Quran verses from a surah name or number, with Arabic text, the selected language’s default translation, and optional transliteration. Longer passages return the first 50 verses.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `passage` | string | yes | `"Al-Baqarah 255"` | Surah name or number, optionally followed by a verse or range, such as Al-Baqarah 255 or Yasin 1-12. |
| `translation_language` | string | no | `"French"` | Language of Quran.com’s default translation, such as English, French or Urdu. |
| `include_transliteration` | boolean | no | `false` | Include Latin-script transliteration of each verse, such as for Yasin 1-12. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "passage"
  ],
  "properties": {
    "passage": {
      "type": "string",
      "description": "Surah name or number, optionally followed by a verse or range, such as Al-Baqarah 255 or Yasin 1-12.",
      "examples": [
        "Al-Baqarah 255",
        "Yasin 1-12",
        "36"
      ]
    },
    "translation_language": {
      "type": "string",
      "default": "English",
      "description": "Language of Quran.com’s default translation, such as English, French or Urdu.",
      "examples": [
        "French"
      ]
    },
    "include_transliteration": {
      "type": "boolean",
      "default": true,
      "description": "Include Latin-script transliteration of each verse, such as for Yasin 1-12.",
      "examples": [
        false
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "passage": "Al-Baqarah 255"
    },
    {
      "passage": "Yasin 1-12",
      "translation_language": "French",
      "include_transliteration": false
    },
    {
      "passage": "36"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `verses` | array |  |  |
| `verses[].link` | string | `"https://quran.com/2:255"` |  |
| `verses[].reference` | string | `"2:255"` |  |
| `verses[].arabic_text` | string | `"يسٓ"` |  |
| `verses[].translation` | string | `"Yâ-Sîn."` |  |
| `verses[].translator_name` | string or null | `"Dr. Mustafa Khattab, The Clear Quran"` |  |
| `verses[].transliteration` | string or null | `"Allahu la ilaha illahuwa alhayyu alqayyoomu la ta/khuthuhusinatun wala nawmun lahu ma fee assamawatiwama fee al-ardi ma` |  |
| `surah_name_arabic` | string | `"البقرة"` | Surah name in Arabic. |
| `surah_name_english` | string | `"Al-Baqarah"` | English transliteration of the surah name. |
| `surah_meaning_english` | string | `"The Cow"` | English meaning of the surah name. |

**Example input**

```json
{
  "passage": "Al-Baqarah 255"
}
```

**Example output**

```json
{
  "verses": [
    {
      "link": "https://quran.com/2:255",
      "reference": "2:255",
      "arabic_text": "ٱللَّهُ لَآ إِلَـٰهَ إِلَّا هُوَ ٱلْحَىُّ ٱلْقَيُّومُ ۚ لَا تَأْخُذُهُۥ سِنَةٌ وَلَا نَوْمٌ ۚ لَّهُۥ مَا فِى ٱلسَّمَـٰوَٰتِ وَمَا فِى ٱلْأَرْضِ ۗ مَن ذَا ٱلَّذِى يَشْفَعُ عِندَهُۥٓ إِلَّا بِإِذْنِهِۦ…",
      "translation": "Allah! There is no god ˹worthy of worship˺ except Him, the Ever-Living, All-Sustaining. Neither drowsiness nor sleep overtakes Him. To Him belongs whatever is in the heavens and whatever is on the ear…",
      "translator_name": "Dr. Mustafa Khattab, The Clear Quran",
      "transliteration": "Allahu la ilaha illahuwa alhayyu alqayyoomu la ta/khuthuhusinatun wala nawmun lahu ma fee assamawatiwama fee al-ardi man tha allatheeyashfaAAu AAindahu illa bi-ithnihi yaAAlamu mabayna aydeehim wama k…"
    }
  ],
  "surah_name_arabic": "البقرة",
  "surah_name_english": "Al-Baqarah",
  "surah_meaning_english": "The Cow"
}
```

### Search quran

Operation `search_quran`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find Quran.com verses matching a word or topic, with Arabic text and a translation in the selected language. Results follow Quran.com search order; translations vary by verse.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"patience"` | Words or a topic to find in the Quran, such as patience or charity. |
| `language` | string | no | `"Spanish"` | Language of translations to search and return, such as English, Spanish, or French. |
| `max_results` | integer | no | `20` | Maximum number of verses to return, from 1 to 50, such as 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "examples": [
        "patience"
      ],
      "minLength": 1,
      "description": "Words or a topic to find in the Quran, such as patience or charity."
    },
    "language": {
      "type": "string",
      "default": "English",
      "examples": [
        "Spanish"
      ],
      "description": "Language of translations to search and return, such as English, Spanish, or French."
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "examples": [
        20
      ],
      "description": "Maximum number of verses to return, from 1 to 50, such as 20.",
      "x-fous-developer": true
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "patience"
    },
    {
      "query": "caridad",
      "language": "Spanish",
      "max_results": 50
    },
    {
      "query": "nonexistenttwordxyzzzzz"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `verses` | array |  | Verses in Quran.com search order. |
| `verses[].link` | string | `"https://quran.com/70/5"` | Link to the verse on Quran.com. |
| `verses[].reference` | string | `"70:5"` | Surah and verse number, such as 2:153. |
| `verses[].surah_name` | string | `"Al-Ma'arij"` | Name of the surah. |
| `verses[].arabic_text` | string | `"فَٱصْبِرْ صَبْرًا جَمِيلًا"` | Arabic verse text. |
| `verses[].translation_text` | string or null | `"So, observe patience, a good patience."` | Translation text in the selected language, or null when unavailable. |

**Example input**

```json
{
  "query": "patience"
}
```

**Example output**

```json
{
  "verses": [
    {
      "link": "https://quran.com/70/5",
      "reference": "70:5",
      "surah_name": "Al-Ma'arij",
      "arabic_text": "فَٱصْبِرْ صَبْرًا جَمِيلًا",
      "translation_text": "So, observe patience, a good patience."
    },
    {
      "link": "https://quran.com/16/127",
      "reference": "16:127",
      "surah_name": "An-Nahl",
      "arabic_text": "وَٱصْبِرْ وَمَا صَبْرُكَ إِلَّا بِٱللَّهِ ۚ وَلَا تَحْزَنْ عَلَيْهِمْ وَلَا تَكُ فِى ضَيْقٍ مِّمَّا يَمْكُرُونَ",
      "translation_text": "And bear with patience, (O Muhammad) - and your patience is only because of the help of Allah - and do not grieve over them, nor feel distressed by their evil plans."
    },
    {
      "link": "https://quran.com/46/35",
      "reference": "46:35",
      "surah_name": "Al-Ahqaf",
      "arabic_text": "فَٱصْبِرْ كَمَا صَبَرَ أُو۟لُوا۟ ٱلْعَزْمِ مِنَ ٱلرُّسُلِ وَلَا تَسْتَعْجِل لَّهُمْ ۚ كَأَنَّهُمْ يَوْمَ يَرَوْنَ مَا يُوعَدُونَ لَمْ يَلْبَثُوٓا۟ إِلَّا سَاعَةً مِّن نَّهَارٍۭ ۚ بَلَـٰغٌ ۚ فَهَلْ يُه…",
      "translation_text": "Then have patience (O Muhammad) even as the stout of heart among the messengers (of old) had patience, and seek not to hasten on (the doom) for them. On the day when they see that which they are promi…"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@quran-com",
  "visibility": "public",
  "operation": "get_verses",
  "version": 1,
  "input": {
    "passage": "Al-Baqarah 255"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@quran-com\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_verses\",\n  \"version\": 1,\n  \"input\": {\n    \"passage\": \"Al-Baqarah 255\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@quran-com",
  "visibility": "public",
  "operation": "get_verses",
  "version": 1,
  "input": {
    "passage": "Al-Baqarah 255"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/quran-com`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_verses`: Get verses. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_quran`: Search quran. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-quran-com https://api.fous.com/mcp/tools/quran-com --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Read a selected passage with its translation
- Compare verse translations across languages
- Find verses about a topic
- Add Arabic verses and transliteration to study materials

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Quran.com tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Quran.com account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from quran.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### How can I read a specific surah or verse?

Get verses takes a surah name or number, optionally with a verse or range, and returns the passage.

### How can I find verses about a topic?

Search quran finds matching verses from a word or topic query.

### Can I get verse transliteration?

Get verses can include Latin-script transliteration when requested.

## Related

- [Bible Gateway API](https://fous.com/tools/bible-gateway.md): Bible Gateway provides passage readings up to one chapter, searches returning up to 100 related verses, and a daily verse that may differ by date or translation availability.
- [Al Jazeera API](https://fous.com/tools/al-jazeera.md): Al Jazeera provides news and analysis, current section headlines and article details, plus keyword-searchable articles; searches and live blogs may show only leading matches or latest updates.
- [BrainyQuote API](https://fous.com/tools/brainyquote.md): BrainyQuote returns topic-matched quotes in displayed order, a person’s description and up to 100 quotes with topic tags and links, or the quote shown for the chosen daily category and BrainyQuote’s current day.
- [Poetry Foundation API](https://fous.com/tools/poetry-foundation.md): Poetry Foundation provides poems, poets, and poetry resources; poem searches follow its search order, while full text is limited to publicly available poems.
- [Wikipedia API](https://fous.com/tools/wikipedia.md): Wikipedia returns article summaries, images, facts, relevant search matches, readable text and daily historical events, plus human-view counts from July 2015 onward.
- [Dictionary.com API](https://fous.com/tools/dictionary-com.md): Dictionary.com provides definitions, pronunciations, audio, examples, and word origins, plus ranked synonyms and antonyms for public Thesaurus.com entries; some word details may be unavailable.
- [Goodreads API](https://fous.com/tools/goodreads.md): Goodreads returns public book searches, matched-book details with variable editions, popular or newest reviews, author books by popularity or date, and up to 100 quotes.
- [Coursera API](https://fous.com/tools/coursera.md): Coursera offers courses, certificates, projects, and degrees; search results follow Coursera’s order, and publicly displayed prices and availability may vary by location.
- [All Education tools](https://fous.com/tools/category/education)