Quran AI Search API

Overview

The AI search API matches natural-language queries to surahs and verses in the Quran using semantic AI. It is designed for integrators who want theme-based discovery without building their own search index or LLM pipeline.

• Returns a single JSON response you can parse with any HTTP client.
• Writes each result's relevance blurb in the language you pass in, or auto-detects the query language (detectedLanguage) when you omit it.
• Returns structured surah and verse numbers your app can link to.

Endpoint

Send a JSON body with the user's search phrase. The API responds with a single JSON object containing the matched references.

POST https://openquran.app/api/ai-search

Headers

Request

The request body is a single JSON object:

{
  "query": "patience in hardship",
  "language": "en"
}

Constraints

• Query must be 2–300 characters after trimming.
• language is optional: an ISO 639-1 code (e.g. en, ar, fr) for the relevance explanations. When omitted or invalid, the language is auto-detected from the query.
• At most 12 results per query.
• Leading and trailing whitespace is stripped.

Response

Successful requests return HTTP 200 with a JSON object.

Content-Type: application/json

{
  "ok": true,
  "results": [
    {
      "type": "surah",
      "surah": 2,
      "relevance": "Covers patience through trials."
    },
    {
      "type": "verse",
      "surah": 2,
      "ayah": 255,
      "relevance": "Ayat al-Kursi speaks of steadfastness in faith."
    }
  ],
  "detectedLanguage": "en"
}

Each item in results includes a relevance field. That text is written in the language you requested, or in the detected query language (detectedLanguage) when no language was provided — for example, an Arabic query yields Arabic relevance blurbs.

Top-level fields

Result types

Each result is a tagged object — either a whole surah or a single verse:

// Whole surah reference
{ "type": "surah", "surah": 2, "relevance": "One sentence explaining the match." }

// Single verse reference
{ "type": "verse", "surah": 2, "ayah": 255, "relevance": "One sentence explaining the match." }

• surah — Surah number, 1–114.
• ayah — 1-based verse number within the surah (verse results only).
• relevance — One-sentence explanation of why the reference matches, written in the requested language or the detected query language. Null for quick-reference lookups.

Quick reference

Bare surah numbers and verse references skip the AI model and resolve instantly:

• 2 — navigate to Surah 2
• 2:255 — navigate to verse 255 of Surah 2

Quick-reference queries return immediately with relevance set to null on each result.

Rate limits

To keep the service free and available, each client IP is limited to 10 requests per 60 seconds.

• Limits are tracked per IP address using standard proxy headers (`X-Forwarded-For`, `X-Real-IP`).
• When limited, the API returns HTTP 429 with a `Retry-After` header (seconds until you can retry).
• Automated scraping, bulk querying, or attempts to circumvent limits may result in blocking.

{
  "ok": false,
  "error": "Too many requests. Please slow down."
}

Error responses

Failed requests return a JSON body with ok set to false and a short error message.

All error responses use the shape: 'ok': false, 'error': "message".

Code examples

cURL

curl -X POST 'https://openquran.app/api/ai-search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"patience in hardship"}'

JavaScript

const response = await fetch('https://openquran.app/api/ai-search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'patience in hardship' }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error ?? response.statusText);
}

const data = await response.json();
console.log(data.results);

Disclaimer

Results are generated by an AI model and may be incomplete or imperfect. They are pointers to help people explore the Quran — not religious rulings or authoritative interpretation. Always read verses in their full context.

By using this API you agree to our Terms of Service and Privacy Policy.