Overview
RAG-powered Islamic Q&A over the Quran, Hadith, scholarly fatwa and Seerah history.
Seerah AI answers Islamic questions by retrieving from a corpus of Quran, Hadith, scholarly fatwa and Seerah history, then reasoning over what it found. Every answer comes back with the sources it was built from, so a reader can check it rather than trust it.
Base URL
https://api-seerahai.karmat-hq.comInteractive reference: Swagger UI · OpenAPI document
Two ways in
The deployment serves two independent audiences, and which one you are decides both the header you send and the paths you can reach.
| Caller | Scheme | Header | Endpoints |
|---|---|---|---|
| External applications | API key | X-API-Key | /api/v1/** |
| Web and mobile end users | Supabase Auth JWT | Authorization: Bearer | /api/chat, /api/conversations/**, /api/auth/** |
Integrations only need the API key
/api/v1. The Supabase-authenticated routes exist for the first-party browser app and are not part of the integration surface.Integration endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/auth/request-access | Ask for a key. Public. |
| POST | /api/v1/chat | Ask a question |
| GET | /api/v1/conversations | List an end user's threads |
| GET | /api/v1/conversations/{id} | Read one thread |
| DELETE | /api/v1/conversations/{id} | Delete a thread |
| GET | /api/v1/status | Knowledge-base readiness and your limits |
| GET | /api/v1/auth/keys/me | Introspect your own key |
| POST | /api/v1/auth/keys/rotate | Rotate your key |
| POST | /api/v1/auth/keys/revoke | Revoke your key |
| GET | /health | Liveness check, no auth |
The remaining /api/v1/auth/** endpoints (reviewing the request queue, minting keys for others) require an admin key. See Access and API keys.
Per-user isolation
Pass an end_user_id and every conversation is namespaced to the pair (your key, end_user_id). One of your users can never read another's thread, and no other integration can read yours.
curl -X POST "https://api-seerahai.karmat-hq.com/api/v1/chat" \
-H "X-API-Key: $SEERAH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What does the Quran say about patience?",
"end_user_id": "user-8842"
}'Use your own opaque user id
end_user_id is echoed back and stored. Send your internal identifier, not an email address, a phone number or a name. There is no reason for us to hold that, and every reason for you not to send it.Checking readiness
/api/v1/statusReports how many documents are indexed per corpus, whether the vector store is ready to serve, and the limits attached to your key. Worth calling at startup: an empty corpus answers questions badly rather than failing loudly.
{
"status": "ready",
"hadith_docs": 34291,
"quran_docs": 6236,
"scholarqa_docs": 12480,
"history_docs": 2911,
"store_ready": true,
"key_id": "a1b2c3d4",
"role": "client",
"rate_limit_per_minute": 60
}