{
  "openapi": "3.1.0",
  "info": {
    "title": "Rhenuma AI Official Developer API",
    "version": "1.0.0",
    "description": "Comprehensive, ultra-low latency REST API for Islamic artificial intelligence reasoning, Quran reading and audio recitation, Sihah Sittah Hadith search, Hisnul Muslim supplications, Zakat calculations, astronomical prayer times, and Kaaba Qibla bearing.",
    "contact": {
      "name": "Rhenuma AI Developer Support",
      "url": "https://rhenuma.com/api-docs.html",
      "email": "api@rhenuma.com"
    },
    "license": {
      "name": "MIT / Educational Fair Use",
      "url": "https://rhenuma.com/terms.html"
    }
  },
  "servers": [
    {
      "url": "https://rhenuma.com",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:8888",
      "description": "Local Development (Netlify Dev)"
    }
  ],
  "paths": {
    "/api/v1/chat": {
      "post": {
        "summary": "Create Chat & Islamic Reasoning Completion",
        "description": "Submits a user prompt or multi-turn conversation to the Groq LPU engine under strict classical Islamic theological guardrails (Quran, Sihah Sittah, 4 Madhhabs). Automatically detects Quranic citations and extracts verse audio streams.",
        "operationId": "createChatCompletion",
        "parameters": [
          {
            "$ref": "#/components/parameters/RateLimitHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              },
              "example": {
                "prompt": "What are the virtues of reciting Ayatul Kursi before sleeping?",
                "model": "llama-3.3-70b-versatile",
                "temperature": 0.6,
                "max_tokens": 2048
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful chat completion response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/429TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/500InternalError"
          }
        }
      }
    },
    "/api/v1/quran": {
      "get": {
        "summary": "Fetch Quran Surahs, Ayats, and Alafasy Audio",
        "description": "Retrieve individual Surahs, specific Ayahs in Uthmani script with English translations, or perform semantic text search across the Quran with high-fidelity Mishary Alafasy audio streams.",
        "operationId": "getQuran",
        "parameters": [
          {
            "name": "surah",
            "in": "query",
            "required": false,
            "description": "Surah chapter number (1-114)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 114
            }
          },
          {
            "name": "ayah",
            "in": "query",
            "required": false,
            "description": "Ayah verse number within the Surah",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Keyword search query across the Quran translation",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quran data retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuranResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "429": {
            "$ref": "#/components/responses/429TooManyRequests"
          }
        }
      }
    },
    "/api/v1/hadith": {
      "get": {
        "summary": "Search & Retrieve Canonical Hadith",
        "description": "Lookup authentic Hadith narrations from the classical Sihah Sittah canon (Bukhari, Muslim, Tirmidhi, Abu Dawood, Nasa'i, Ibn Majah).",
        "operationId": "getHadith",
        "parameters": [
          {
            "name": "collection",
            "in": "query",
            "required": false,
            "description": "Collection identifier (bukhari, muslim, tirmidhi, abudawood)",
            "schema": {
              "type": "string",
              "enum": ["bukhari", "muslim", "tirmidhi", "abudawood", "nasai", "ibnmajah"]
            }
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Hadith number in collection",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Keyword search string across English narration",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hadith results returned successfully"
          },
          "429": {
            "$ref": "#/components/responses/429TooManyRequests"
          }
        }
      }
    },
    "/api/v1/duas": {
      "get": {
        "summary": "Retrieve Hisnul Muslim Supplications",
        "description": "Fetches authentic daily supplications with Arabic text, phonetic transliterations, translations, and canonical Hadith references.",
        "operationId": "getDuas",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category name filter (e.g. 'Morning & Evening', 'Anxiety & Sorrow', 'Traveling')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search keyword",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of authentic supplications"
          },
          "429": {
            "$ref": "#/components/responses/429TooManyRequests"
          }
        }
      }
    },
    "/api/v1/utilities": {
      "post": {
        "summary": "Calculate Zakat, Prayer Times & Qibla Direction",
        "description": "Mathematical engine for Islamic utilities including 2.5% Zakat with Nisab checking, GPS astronomical prayer schedules, and forward spherical Qibla trigonometry.",
        "operationId": "computeUtilities",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["zakat", "qibla", "prayer_times"]
                  },
                  "cash": { "type": "number" },
                  "gold": { "type": "number" },
                  "investments": { "type": "number" },
                  "inventory": { "type": "number" },
                  "debt": { "type": "number" },
                  "lat": { "type": "number" },
                  "lng": { "type": "number" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Utility computation result"
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/429TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "RateLimitHeader": {
        "name": "X-API-Key",
        "in": "header",
        "required": false,
        "description": "Optional API Key for elevated rate limits (120 req/min)",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ChatRequest": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The user query or prompt string."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": { "type": "string", "enum": ["system", "user", "assistant"] },
                "content": { "type": "string" }
              },
              "required": ["role", "content"]
            }
          },
          "model": {
            "type": "string",
            "default": "llama-3.3-70b-versatile",
            "description": "Selected model with automatic fallback and failover rotation on exhaustion.",
            "enum": [
              "llama-3.3-70b-versatile",
              "deepseek-r1-distill-llama-70b",
              "qwen-2.5-32b",
              "llama-3.1-70b-versatile",
              "llama-3.1-8b-instant",
              "gemma2-9b-it",
              "mixtral-8x7b-32768",
              "llama-3.2-3b-preview",
              "llama-3.2-1b-preview",
              "llama3-70b-8192",
              "llama3-8b-8192"
            ]
          },
          "max_tokens": {
            "type": "integer",
            "default": 4096,
            "maximum": 4096
          },
          "temperature": {
            "type": "number",
            "default": 0.6,
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "example": "chat.completion" },
          "model": { "type": "string" },
          "reply": { "type": "string" },
          "quran_citations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "arabic": { "type": "string" },
                "translation": { "type": "string" },
                "reference": { "type": "string" },
                "surah": { "type": "integer" },
                "ayah": { "type": "integer" },
                "audio_url": { "type": "string" }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": { "type": "integer" },
              "completion_tokens": { "type": "integer" },
              "total_tokens": { "type": "integer" }
            }
          },
          "provider": { "type": "string", "example": "Rhenuma AI / Groq LPU" }
        }
      },
      "QuranResponse": {
        "type": "object",
        "properties": {
          "surah_number": { "type": "integer" },
          "name_arabic": { "type": "string" },
          "name_english": { "type": "string" },
          "total_ayahs": { "type": "integer" },
          "reciter": { "type": "string" },
          "audio_url": { "type": "string" }
        }
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Invalid input or missing required parameters",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "404NotFound": {
        "description": "Requested resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "429TooManyRequests": {
        "description": "Rate limit quota exceeded",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": { "type": "integer", "example": 429 },
                "error": { "type": "string", "example": "Too Many Requests" },
                "message": { "type": "string" },
                "retry_after_seconds": { "type": "integer" }
              }
            }
          }
        }
      },
      "500InternalError": {
        "description": "Internal server or inference failure",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}