API DOC · v1 · NO AUTH

API documentation

The demo endpoint of Bedir AI: it takes a question, hands the published corpus to the Claude Messages API as document blocks, and returns the answer together with the verbatim passage it was drawn from. CORS is open, so you can call it straight from a browser console.

Endpoints

Endpoint	What it does
POST /api/ask	Answers a question and returns the quotations the answer rests on, with ids and publisher links.
GET /api/waitlist	Returns the number of stored waitlist signups: `{"count": n}`.
POST /api/waitlist	Adds an email: `{email, lang, source}`. A duplicate returns 200; if the honeypot field `_gotcha` is filled nothing is stored.
GET /data/corpus.json	The 111 documents the answers come from, including its version and source list.

Request

curl -X POST https://bedirsavasi.com/api/ask \ -H "content-type: application/json" \ -d '{"q": "Which verse describes the help given at Badr?", "lang": "en"}'

Request

Field	Type	Required	Notes
q	string	yes	The question, 1-400 characters. Longer returns `bad_question`.
lang	string	no	`tr` · `en` · `de` · `ar`; default `en`. Answers come back in the language of the question; this field picks the language of the interface strings.

Response

This record is from a real call on 7 October 2026, with provider = claude: production answers are produced by claude-haiku-4-5-20251001. When the endpoint's daily budget is spent or Claude is unreachable, the labelled backup engine answers and provider reads fallback; the interface shows the same label.

{
  "answer": [
    {
      "text": "Allah made the angels as a sign of good tidings and to reassure the believers' hearts, and victory is from Allah, the Exalted in Might, the Wise.",
      "cites": [
        {
          "id": "Q3:126",
          "title": "Qur'an 3:126 (Āl ʿImrān)",
          "url": "https://quran.com/3/126",
          "quote": "And Allah made it not except as [a sign of] good tidings for you and to reassure your hearts thereby. And victory is not except from Allah, …"
        }
      ]
    }
  ],
  "model": "claude-haiku-4-5-20251001",
  "provider": "claude",
  "usage": {
    "input": 127,
    "cache_read": 0,
    "cache_write": 30071,
    "output": 113
  },
  "retrieval": {
    "mode": "filtered",
    "documents_sent": 111,
    "corpus_size": 111,
    "matched_terms": 3
  }
}

Field meanings

Field	Meaning
answer[].text	The answer; factual sentences end with an [n] citation marker.
answer[].cites[]	The citation: `id` is the corpus id (Q3:123, B3950, M1763), `title` names the passage as the publisher numbers it, `url` points at quran.com or sunnah.com, `quote` is the verbatim span taken from the document.
provider	`claude` or `fallback`. We name the engine that answered rather than claiming credit for Claude. Answers come from `claude-haiku-4-5-20251001` behind a daily budget on this endpoint.
usage	input / cache_read / cache_write / output token counts; you can see whether prompt caching hit.
retrieval	`documents_sent`: documents shipped per request - always the whole collection, because the cached prefix has to stay identical for every question. `mode`: `filtered` when distinctive terms narrowed the priority list inside the question (up to 24 passages), `full` when they did not.

Errors

Status	Body	When
400	`bad_request`	The body is not JSON.
400	`bad_question`	Question empty or longer than 400 characters.
405	`method_not_allowed`	Any method other than POST.
429	`busy`	More than 8 requests per IP in 60 seconds, or an Anthropic-side rate limit.
500	`not_configured`	The endpoint has no API key set.
200	`refused`	Claude refused to answer; body is empty, status stays 200.
502	`upstream`	Claude was unreachable and the backup engine could not answer either.

Corpus and coverage

We state coverage as it is measured; German is thinner than the rest.

Corpus and coverage

Collection	Documents	Languages
Qur'an - the Badr passages	41 (Āl ʿImrān 3:12, 3:121-127; Al-Anfāl 8:1-76)	ar 111/111 · en 111/111 · tr 110/111 · de 41/111
Sahih al-Bukhari (Badr / ghazawa chapters)	68	numbered as on sunnah.com
Sahih Muslim	2	numbered as on sunnah.com
Version	2026-10-07	the corpus carries a `version` field

Sources: Tanzil (Uthmani) plus the Diyanet Vakfı, Saheeh International and Bubenheim & Elyas renderings through api.alquran.cloud; hadith via fawazahmed0/hadith-api, numbered to match sunnah.com. Licensing and translation-usage notes are in DATA_NOTES.md.

Try it

Straight from the browser; CORS is open.

HTTP

Limits

Answers are produced by claude-haiku-4-5-20251001: with prompt caching a cold question writes a 30-65k token cache and a warm one pays about 130 fresh input tokens (measured). The endpoint has a daily token budget; past it we stop calling Claude, the backup engine answers, and provider says so.
This is a demo endpoint: no authentication, the rate limit is per IP, and there is no SLA.
The collection is scoped to the Battle of Badr. On a question it does not cover, it says so instead of inventing an answer.
The verbatim span is in quote, but a quotation supporting the wrong claim is a different problem: we wrote the measurement for that (eval/) and have not run it at scale yet.

The code and the corpus behind this page: github.com/mevlanayalcin/bedir-ai