Ahkam101 API

• Ask a question and get the answer in Markdown, in English, Arabic, Farsi or Urdu, in regular or Scholar Mode.
• Follow up on a question; earlier turns are used as context.
• List your questions with their follow-ups, most recently active first.
• Read answers with citations: the book, page and ruling number for every source an answer relies on.
• Read the full ruling text behind any citation.

Answers can also stream as server-sent events, and you can rate answers and check your quota.

The API is part of the Organization plan, for institutions and apps that build on Ahkam101. Quota is shared between the API and the web app for the same account.

Get the Organization plan

1. Create a token. In Settings → API tokens, create a token with the scopes it needs (ask, read, delete). Copy the secret; it is shown once.

2. Ask a question. Send the token in the Authorization header and a fresh Idempotency-Key with every ask.

   export API_BASE="https://ahkam101.com"
   export AHKAM_TOKEN="ahk_live_..."
   
   curl -s "$API_BASE/api/v1/questions" \
     -H "Authorization: Bearer $AHKAM_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"question": "Is it permissible to combine Dhuhr and Asr prayers?"}'

   The response is the answered turn, with its citations:

   {"turn_id": "...", "question_id": "...", "kind": "answered",
    "question": "...", "answer": "<markdown>",
    "citations": [{"document": "Islamic Laws", "page": 148,
                   "ruling_number": "731", "excerpt": "...", "score": 0.91,
                   "language": "en", "chunk_id": "...", "url": "https://..."}],
    "confidence": 0.87, "mode": "regular", "language": "en",
    "created_at": "...", "suggested_followups": ["..."],
    "quality": {"passed": true, "score": 0.94, "issues": []}}

3. Follow up. Ask again under the question_id from step 2; earlier turns are used as context.

   # QID is the question_id from step 2, e.g. with jq:
   # QID=$(curl -s ... | jq -r .question_id)
   curl -s "$API_BASE/api/v1/questions/$QID/turns" \
     -H "Authorization: Bearer $AHKAM_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"question": "What if I am travelling?"}'

Give your agent two things:

1. The API guide to read first: https://ahkam101.com/api/v1/llms.txt
2. A token, sent on every request as Authorization: Bearer <token>.

Have it send a fresh Idempotency-Key with each ask and reuse that key when it retries, so a retry never asks or charges twice.

The full contract is the OpenAPI document, and the API reference lets you browse every route.

• 10 asks a minute, with at most 3 answers in progress at once
• 60 other requests a minute
• A token can carry its own lower caps, set in Settings; a request must fit both the token cap and the account limit.
• All requests from one client IP share a ceiling of 300 a minute, whatever token they carry; more than 20 failed authentications a minute from one IP are answered 429.
• Quota: 1000 answered questions a month, up to 200 of them in Scholar Mode, shared between the API and the web app

Rate limits count per account, across all its tokens. Clarifying questions, notices and failures are not charged. Over a rate limit, the API answers 429 rate_limited or too_many_in_flight with a Retry-After header. When the quota runs out, asks return 429 limit_exceeded with the usage object.

Answered asks carry X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. Every response carries an X-Request-ID; quote it when you report a problem.

Questions about the API, or something not working as documented? Send us feedback and include the request you sent and the response you got.