{ "openapi": "3.1.0", "info": { "title": "Amanah Sunnah API", "version": "1.1.0", "description": "The most comprehensive Islamic knowledge API following the methodology of Ahlus Sunnah wal Jamaah (Salaf).\n\n## Data Coverage\n- **6,236** Quran verses with Tafsir Ibn Kathir\n- **36,390** Hadith from 7 major collections (Kutub Sittah + Muwatta Malik)\n- **18,298** Narrators from Taqrib At-Tahdzib\n- **66** Chapters of Kitab At-Tawhid\n- **97** Daily Sunnah practices\n- **50** Duas from authentic hadith\n- **99** Asmaul Husna (Names of Allah)\n- **42** Hadith Nawawi\n\n## Features\n- Hybrid semantic search (pgvector + BM25)\n- AI-powered Q&A with RAG from 67,458+ verified references\n- Kajian webhook for YouTube video transcription & AI summarization\n- Hadith grading from Shaykh Al-Albani, Ahmad Shakir, Zubair Ali Zai\n\n## Authentication\nAll endpoints require an API key via X-API-Key header.\nGet your free key at [Developer Portal](https://sunnah.amanahagent.cloud/developers).\n\n## Rate Limits\n- **60 requests/minute**\n- **10,000 requests/day**\n\nCompletely free. No paid tiers. API key is for identification and abuse prevention only.\nExceeding limits returns 429 Too Many Requests.\n\n## Methodology\nAll data follows the understanding of the Salafus Shalih. No AI-generated content in the knowledge base. Hadith grading from recognized muhaddithin only.", "contact": { "name": "Amanah Sunnah", "url": "https://sunnah.amanahagent.cloud/developers", "email": "support@amanahagent.cloud" }, "license": { "name": "Free for non-commercial use" } }, "servers": [ { "url": "https://sunnah.amanahagent.cloud/api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "paths": { "/quran/{key}": { "get": { "summary": "Get Quran ayah", "description": "Get Quran verse with Arabic text (Uthmani), Indonesian translation, and Tafsir Ibn Kathir.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Surah:Ayah format", "schema": { "type": "string" }, "example": "2:255" } ], "responses": { "200": { "description": "Quran verse data", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "surah": { "type": "integer" }, "ayah": { "type": "integer" }, "text_arabic": { "type": "string" }, "text_indonesian": { "type": "string" }, "tafsir": { "type": "string" } } } } } } }, "tags": [ "Quran & Tafsir" ] } }, "/hadith/{key}": { "get": { "summary": "Get hadith by key", "description": "Get hadith with Arabic text, translation, sanad chain, and grading from muhaddithin.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "collection:number format", "schema": { "type": "string" }, "example": "bukhari:1" } ], "responses": { "200": { "description": "Hadith data", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "collection": { "type": "string" }, "text_arabic": { "type": "string" }, "text_indonesian": { "type": "string" }, "grades": { "type": "string" }, "sanad": { "type": "string" } } } } } } }, "tags": [ "Hadith" ] } }, "/search": { "post": { "summary": "Hybrid semantic + keyword search", "description": "Search across Quran, Hadith, and Rijal using AI-powered hybrid search (pgvector + BM25).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "Search query", "example": "keutamaan shalat malam" }, "type": { "type": "string", "enum": [ "quran", "hadith", "rijal", "all" ], "description": "Filter by content type", "example": "hadith" }, "limit": { "type": "integer", "description": "Max results (1-20)", "example": 5 } } } } } }, "responses": { "200": { "description": "Search results with relevance scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "key": { "type": "string" }, "text": { "type": "string" }, "score": { "type": "number" } } } }, "total": { "type": "integer" } } } } } } }, "tags": [ "AI & Search" ] } }, "/ask": { "post": { "summary": "AI Q&A with dalil", "description": "Ask any Islamic question. AI answers with dalil from 67,458 verified references (RAG + Gemini).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "Your question in any language", "example": "Apa hukum puasa senin kamis?" } } } } } }, "responses": { "200": { "description": "AI answer with sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "key": { "type": "string" }, "text": { "type": "string" } } } } } } } } } }, "tags": [ "AI & Search" ] } }, "/tafsir/{key}": { "get": { "summary": "Get Tafsir Ibn Kathir for an ayah", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2:255" } ], "responses": { "200": { "description": "Tafsir text" } }, "tags": [ "Quran & Tafsir" ] } }, "/rijal": { "get": { "summary": "Search hadith narrators", "description": "Search 18,298 narrators from Taqrib At-Tahdzib with grading and biography.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Narrator name (Arabic or Latin)", "schema": { "type": "string" }, "example": "سفيان" }, { "name": "limit", "in": "query", "description": "Max results", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "List of narrators", "content": { "application/json": { "schema": { "type": "object", "properties": { "narrators": { "type": "array", "items": { "type": "object", "properties": { "name_arabic": { "type": "string" }, "name_latin": { "type": "string" }, "grade": { "type": "string" }, "generation": { "type": "string" }, "death_year": { "type": "string" } } } } } } } } } }, "tags": [ "Hadith" ] } }, "/nawawi": { "get": { "summary": "Get all 42 Hadith Nawawi", "responses": { "200": { "description": "Array of hadith nawawi with Arabic, Indonesian, and explanation" } }, "tags": [ "Hadith" ] } }, "/doa": { "get": { "summary": "Get daily duas from hadith", "description": "Returns 50 authentic duas with Arabic text, transliteration, translation, and source hadith.", "parameters": [ { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string", "enum": [ "pagi", "petang", "shalat", "makan", "tidur", "safar", "umum" ] }, "example": "pagi" } ], "responses": { "200": { "description": "List of duas", "content": { "application/json": { "schema": { "type": "object", "properties": { "doas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "arabic": { "type": "string" }, "transliteration": { "type": "string" }, "translation": { "type": "string" }, "source": { "type": "string" }, "category": { "type": "string" } } } } } } } } } }, "tags": [ "Islamic Knowledge" ] } }, "/amalan": { "get": { "summary": "Get sunnah daily practices", "description": "Returns list of sunnah amalan (daily practices) with Arabic text, translation, and dalil.", "parameters": [ { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string", "enum": [ "dzikir", "doa", "shalat", "puasa", "adab", "ibadah" ] }, "example": "dzikir" } ], "responses": { "200": { "description": "List of amalan", "content": { "application/json": { "schema": { "type": "object", "properties": { "amalan": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "arabic": { "type": "string" }, "translation": { "type": "string" }, "dalil": { "type": "string" }, "category": { "type": "string" } } } } } }, "example": { "amalan": [ { "id": "1", "title": "Dzikir Pagi", "arabic": "سبحان الله", "translation": "Maha Suci Allah", "dalil": "HR. Muslim", "category": "dzikir" } ] } } } } }, "tags": [ "Islamic Knowledge" ] } }, "/asmaul-husna": { "get": { "summary": "Get 99 Names of Allah", "responses": { "200": { "description": "Array of Asmaul Husna with Arabic, transliteration, and meaning" } }, "tags": [ "Islamic Knowledge" ] } }, "/tawhid": { "get": { "summary": "Get Kitab At-Tawhid chapters", "responses": { "200": { "description": "Array of chapters with dalil" } }, "tags": [ "Islamic Knowledge" ] } }, "/aqidah": { "get": { "summary": "Get Aqidah Salaf explanations", "responses": { "200": { "description": "Array of aqidah topics" } }, "tags": [ "Islamic Knowledge" ] } }, "/figures": { "get": { "summary": "Get Islamic figures", "responses": { "200": { "description": "Array of key Islamic figures with biographies" } }, "tags": [ "Islamic Knowledge" ] } }, "/maudhu": { "get": { "summary": "Get known fabricated hadiths", "responses": { "200": { "description": "Array of maudhu (fabricated) hadiths with scholar rulings" } }, "tags": [ "Hadith" ] } }, "/kajian/webhook": { "post": { "deprecated": true, "summary": "[Deprecated] Use /lecture/webhook instead", "description": "Legacy endpoint. Please use /lecture/webhook with English field names.", "tags": ["Lectures"] } }, "/lecture/webhook": { "post": { "summary": "Submit lecture for AI processing", "description": "Submit a YouTube lecture URL for transcription and AI summary. Requires admin approval before processing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["youtube_url"], "properties": { "youtube_url": { "type": "string", "description": "YouTube video URL", "example": "https://www.youtube.com/watch?v=xxxxx" }, "title": { "type": "string", "description": "Lecture title", "example": "Riyadhus Shalihin - Bab Ikhlas" }, "speaker": { "type": "string", "description": "Speaker/ustadz name", "example": "Ustadz Fulan" }, "topic": { "type": "string", "enum": ["Aqidah", "Tauhid", "Fiqh", "Akhlak", "Tafsir", "Hadits", "Shalat", "Manhaj", "Tarbiyah", "Muamalah", "Ibadah", "Dzikir", "Adab"], "description": "Topic category" }, "mosque_name": { "type": "string", "description": "Mosque name (partial match supported)", "example": "MAIS" }, "mosque_city": { "type": "string", "description": "City name" } } } } } }, "responses": { "201": { "description": "Lecture submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "pending" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing youtube_url or invalid URL" }, "401": { "description": "Invalid or missing API key" } }, "tags": ["Lectures"] } }, "/lecture": { "get": { "summary": "List published Islamic lectures", "description": "Returns published lectures with AI-generated summaries, speaker info, topic, duration, and associated mosque.", "parameters": [ { "name": "q", "in": "query", "description": "Search by title, speaker, or topic", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "description": "Filter by topic", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max results (default: 20, max: 50)", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "List of lectures", "content": { "application/json": { "schema": { "type": "object", "properties": { "lectures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "youtubeUrl": { "type": "string" }, "speaker": { "type": "string" }, "topic": { "type": "string" }, "duration": { "type": "integer", "description": "Duration in seconds" }, "summary": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "mosque": { "type": "object", "properties": { "name": { "type": "string" }, "city": { "type": "string" } } } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } }, "tags": ["Lectures"] } }, "/mosque": { "get": { "summary": "List verified Salafi mosques", "description": "Returns all verified mosques following Ahlus Sunnah wal Jama'ah manhaj with location data.", "parameters": [ { "name": "q", "in": "query", "description": "Search by name or city (min 2 chars)", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "description": "Latitude for proximity search", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "description": "Longitude for proximity search", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of mosques", "content": { "application/json": { "schema": { "type": "object", "properties": { "mosques": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "phone": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } }, "tags": ["Community"] } }, "/school": { "get": { "summary": "List verified Salafi schools", "description": "Returns all verified schools, madrasah, and pesantren following Salaf manhaj with education level and location.", "parameters": [ { "name": "q", "in": "query", "description": "Search by name or city (min 2 chars)", "schema": { "type": "string" } }, { "name": "level", "in": "query", "description": "Filter by education level", "schema": { "type": "string", "enum": ["TK", "SD", "SMP", "SMA", "Pesantren"] } }, { "name": "lat", "in": "query", "description": "Latitude for proximity search", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "description": "Longitude for proximity search", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of schools", "content": { "application/json": { "schema": { "type": "object", "properties": { "schools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "phone": { "type": "string" }, "website": { "type": "string" }, "educationLevel": { "type": "string" }, "curriculumType": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } }, "tags": ["Community"] } } }, "tags": [ { "name": "Quran & Tafsir", "description": "Al-Quran verses and Tafsir Ibn Kathir" }, { "name": "Hadith", "description": "Hadith collections, narrators, and grading" }, { "name": "Islamic Knowledge", "description": "Tawhid, Aqidah, Amalan, Doa, and more" }, { "name": "AI & Search", "description": "Semantic search and AI-powered Q&A" }, { "name": "Lectures", "description": "Islamic lectures with AI summaries" }, { "name": "Community", "description": "Verified mosques and schools directory" } ] }