API Documentation

1. Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme.

Header Format

Authorization: Bearer mai_live_your_api_key_here

API keys are prefixed with mai_live_ followed by 32 hexadecimal characters. You can generate keys from the developer dashboard.

Important: Your API key is shown only once when created. Store it securely and never expose it in client-side code or public repositories.

2. Endpoint Reference

POST/api/v1/ask

Ask a question about Islam. Returns an AI-generated answer backed by verified Islamic sources.

Parameter	Type	Required	Description
question	string	Yes	Your question about Islam (max 2000 chars)

GET/api/v1/ask

Returns API information and documentation links. No authentication required.

3. Request Format

Send a POST request with a JSON body containing your question.

cURL Example

curl -X POST https://muslimai.uk/api/v1/ask \
  -H "Authorization: Bearer mai_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the conditions for a valid prayer in Islam?"
  }'

JavaScript (fetch)

const response = await fetch('https://muslimai.uk/api/v1/ask', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mai_live_abc123def456...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question: 'What are the conditions for a valid prayer in Islam?'
  })
});

const data = await response.json();

Python (requests)

import requests

response = requests.post(
    'https://muslimai.uk/api/v1/ask',
    headers={
        'Authorization': 'Bearer mai_live_abc123def456...',
        'Content-Type': 'application/json'
    },
    json={'question': 'What are the conditions for a valid prayer in Islam?'}
)

data = response.json()

4. Response Format

Successful responses return a JSON object with the answer, source citations, and usage metadata.

200 OK - Success Response

{
  "answer": "The conditions for a valid prayer (salah) in Islam include...",
  "sources": [
    {
      "title": "Sahih al-Bukhari, Book of Prayer",
      "score": 0.94
    },
    {
      "title": "Fiqh al-Sunnah, Chapter on Salah",
      "score": 0.89
    }
  ],
  "usage": {
    "tokensIn": 1450,
    "tokensOut": 250,
    "latencyMs": 1120,
    "dailyRemaining": 8,
    "monthlyRemaining": 295,
    "rateLimitRemaining": 4
  }
}

Response Fields

Field	Type	Description
answer	string	The AI-generated answer to your question
sources	array	Islamic sources referenced (title and relevance score)
usage.tokensIn	number	Input tokens consumed
usage.tokensOut	number	Output tokens generated
usage.latencyMs	number	Response time in milliseconds
usage.dailyRemaining	number	Remaining requests for today
usage.monthlyRemaining	number	Remaining requests for this month

5. Rate Limits

Rate limits are applied per API key. Limits vary by plan tier.

Plan	Per Minute	Daily	Monthly	Max Tokens
Free	5	10	300	300
Basic	30	500	15,000	500
Pro	60	5,000	150,000	800
Enterprise	120	Unlimited	Unlimited	2,000

Rate Limit Headers

Every response includes rate limit information in the headers:

X-RateLimit-Limit: 5        # Requests allowed per minute
X-RateLimit-Remaining: 3    # Remaining requests in current window
X-RateLimit-Reset: <ISO>    # When the current window resets
Retry-After: 60             # Seconds to wait (only on 429 responses)

6. Error Codes

The API uses standard HTTP status codes. Errors return a JSON object with an error field.

400Bad Request

Invalid or missing request body. Ensure you send valid JSON with a "question" field.

{"error": "Question is required and must be a non-empty string"}

401Unauthorized

Missing, invalid, or revoked API key.

{"error": "Invalid or revoked API key"}

402Payment Required

Daily or monthly usage limit exceeded. Upgrade your plan or wait for the limit to reset.

{"error": "Daily usage limit exceeded", "used": 10, "limit": 10}

429Too Many Requests

Per-minute rate limit exceeded. Wait and retry after the Retry-After period.

{"error": "Rate limit exceeded", "limit": 5, "remaining": 0}

500Internal Server Error

Something went wrong on our end. Retry after a brief delay. If persistent, contact support.

{"error": "Internal server error"}

7. Best Practices

Keep Keys Secure

Never expose your API key in client-side JavaScript, public repositories, or mobile apps. Use environment variables and server-side proxying.

Handle Errors Gracefully

Always check the HTTP status code. Implement exponential backoff for 429 and 500 errors. Parse the error message for user-friendly feedback.

Cache Responses

For frequently asked questions, cache responses locally to reduce API calls and improve performance. The same question will generally return consistent answers.

Monitor Usage

Check the usage object in every response to track your remaining quota. Use the developer dashboard for detailed analytics.

Ask Specific Questions

More specific questions yield better, more focused answers. Instead of "Tell me about Islam", ask "What are the conditions for breaking a fast in Ramadan according to Hanafi fiqh?"

Respect Rate Limits

Use the X-RateLimit-Remaining header to proactively throttle your requests rather than waiting for 429 errors.

Ready to start building?

Get Your API Key