Developer API

Access authentic Islamic knowledge through our Criterion's API. Use the APIs to find relevant verses and hadiths for any topic. Our semantic similarity search understands the meaning and intent of your queries, matching conceptually similar content even when exact words differ—search 6,236 Quran verses and 21,641 authentic hadiths from 6 major collections with AI-powered precision.

🔍 Try Quran Search Live📚 Try Hadith Search Live

Quick Start

JavaScript/TypeScript:

// Search Quran
const response = await fetch(
  'https://criterion.life/api/v1/quran/search?q=patience&limit=5'
);
const data = await response.json();

// Search Hadith  
const response = await fetch(
  'https://criterion.life/api/v1/hadith/search?q=charity&collections=bukhari,muslim'
);
const data = await response.json();

cURL:

# Search Quran
curl "https://criterion.life/api/v1/quran/search?q=patience&limit=5"

# Search Hadith
curl "https://criterion.life/api/v1/hadith/search?q=charity&collections=bukhari,muslim"

Python:

import requests

# Search Quran
response = requests.get(
    'https://criterion.life/api/v1/quran/search',
    params={'q': 'patience', 'limit': 5}
)
data = response.json()

API Endpoints

GET/api/v1/quran/search

Semantic search across 6,236 Quran verses using AI embeddings. Top results include ±2 surrounding verses for context.

Parameters

  • q *required - Search query (1-500 chars)
  • limit optional - Number of results (1-20, default: 7)

Example Response

{
  "results": [
    {
      "verseId": "032c3b98-e9a7-40ad-801e-4c581154d65c",
      "surahNumber": 70,
      "ayahNumber": 5,
      "surahNameEnglish": "Al-Ma'arij",
      "surahNameArabic": "المعارج",
      "textArabic": "فَاصْبِرْ صَبْرًا جَمِيلًا",
      "textEnglish": "So be patient with gracious patience.",
      "similarity": 0.7667777003247903,
      "hasContext": true,
      "contextBefore": [
        {
          "surahNumber": 70,
          "ayahNumber": 4,
          "textArabic": "...",
          "textEnglish": "The angels and the Spirit will ascend to Him..."
        }
      ],
      "contextAfter": [
        {
          "surahNumber": 70,
          "ayahNumber": 6,
          "textArabic": "...",
          "textEnglish": "Indeed, they see it [as] distant,"
        }
      ]
    }
  ],
  "query": "patience",
  "count": 5,
  "language": "en"
}
GET/api/v1/hadith/search

Semantic Similarity search across 21,641 authentic hadiths from 6 major collections

Parameters

  • q *required - Search query (1-500 chars)
  • collections optional - bukhari, muslim, tirmidhi, abudawud, nawawi40, riyadussalihin (comma-separated)
  • grade optional - sahih-only (default), sahih-and-hasan, all
  • limit optional - Number of results (1-15, default: 5)

Example Response

{
  "results": [
    {
      "reference": "Sahih al-Bukhari 2891",
      "collection": "Sahih Bukhari",
      "english": "The Prophet (ﷺ) said, \"Charity is obligatory everyday on every joint of a human being. If one helps a person in matters concerning his riding animal by helping him to ride it or by lifting his luggage on to it, all this will be regarded charity. A good word, and every step one takes to offer the compulsory Congregational prayer, is regarded as charity; and guiding somebody on the road is regarded as charity.\"",
      "arabic": "...",
      "grade": "Sahih",
      "narrator": "Narrated Abu Huraira:",
      "book": "Fighting for the Cause of Allah (Jihaad)",
      "chapter": "The superiority of him who carries the luggage...",
      "sourceUrl": "https://sunnah.com/bukhari:2891",
      "similarity": 0.6108240601445545
    }
  ],
  "query": "charity",
  "count": 5,
  "filters": {
    "collections": [
      "Sahih Bukhari",
      "Sahih Muslim"
    ],
    "gradeFilter": "sahih-only"
  }
}

Key Features

🔍

Semantic Search

Powered by high dimensional embeddings for meaning-based results

📖

Context-Aware

Quran results include ±2 surrounding verses

✅

Authenticity First

Filter by Sahih, Hasan grades

⚡

Fast Responses

~500ms average latency

Rate Limits

Current limits: 10 requests per minute per IP

Rate limit headers included in responses. Need higher limits? Contact us for API keys.

Technology Stack

▸
Embeddings: Google Gemini text-embedding-004 (768-dim)
▸
Database: PostgreSQL + pgvector with HNSW indexes
▸
Vector Search: Cosine similarity
▸
Keyword Search: PostgreSQL ts_rank
▸
Merge Strategy: Reciprocal Rank Fusion (k=60)
▸
Validation: Zod schemas

Support

Questions or need help? We're here to assist:

💬
GitHub Issues
Report bugs or request features
📚
View Source
Open source on GitHub

Ready to build Islamic applications?

Try the Chat InterfaceView Open Source Code