API DOC · v1 · NO AUTH

API dokümantasyonu

Bedir AI'nın demo uç noktası: bir soru alır, yayınlanmış korpusumuzdan belgeleri Claude Messages API'sine document olarak verir, sunucu taraflı atıfla dönen yanıtı ve alıntılandığı metni yayınlar. Açık CORS ile çalışır, yani tarayıcı konsolundan doğrudan deneyebilirsin.

Uç noktalar

Uç nokta	Ne yapar
POST /api/ask	Soruyu yanıtlar; yanıtın dayandığı alıntıları, kimliği ve yayıncı bağlantısını döner.
GET /api/waitlist	Bekleme listesindeki kayıt sayısını döner: `{"count": n}`.
POST /api/waitlist	E-posta ekler: `{email, lang, source}`. Mükerrer kayıt 200 döner, honeypot alanı `_gotcha` doluySA kaydedilmez.
GET /data/corpus.json	Yanıtların türediği 111 belge; sürüm numarası ve kaynak listesini de içerir.

İstek

curl -X POST https://bedirsavasi.com/api/ask \ -H "content-type: application/json" \ -d '{"q": "Bedir'de yardım hangi ayette geçiyor?", "lang": "tr"}'

İstek

Alan	Tür	Zorunlu	Açıklama
q	string	evet	Soru; 1-400 karakter. Üstü `bad_question`.
lang	string	hayır	`tr` · `en` · `de` · `ar`; varsayılan `en`. Yanıt sorunun dilinde gelir, bu alan arayüz dilini seçer.

Yanıt

Bu kayıt 7 Ekim 2026'da gerçek bir çağrıdan alındı ve provider = claude: yanıtlar üretimde claude-haiku-4-5-20251001 ile üretiliyor. Uç noktanın gün bütçesi bittiğinde ya da Claude ulaşılamazda etiketli yedek motor yanıtlar ve provider fallback der; arayüz aynı etiketi gösterir.

{
  "answer": [
    {
      "text": "Bedir'de yardım Al-i İmran 3:123 ayetinde geçmektedir. Ayette şöyle buyurulmaktadır: \"Andolsun, sizler güçsüz olduğunuz halde Allah, Bedir'de de size yardım etmişti.\"",
      "cites": [
        {
          "id": "Q3:123",
          "title": "Âl-i İmrân 3:123",
          "url": "https://quran.com/3/123",
          "quote": "Andolsun, sizler güçsüz olduğunuz halde Allah, Bedir'de de size yardım etmişti.…"
        }
      ]
    }
  ],
  "model": "claude-haiku-4-5-20251001",
  "provider": "claude",
  "usage": {
    "input": 142,
    "cache_read": 0,
    "cache_write": 64610,
    "output": 212
  },
  "retrieval": {
    "mode": "filtered",
    "documents_sent": 111,
    "corpus_size": 111,
    "matched_terms": 1
  }
}

Alanların anlamı

Alan	Anlamı
answer[].text	Yanıtın metni; cümlelerin sonunda [n] atıf işaretleri bulunur.
answer[].cites[]	Atıf: `id` korpus kimliği (Q3:123, B3950, M1763), `title` yayıncı numaralandırmasıyla başlık, `url` quran.com veya sunnah.com bağlantısı, `quote` belgeye birebir ait alıntı parçası.
provider	`claude` veya `fallback`. Hangi motorun cevap verdiğini arayüz de söyler; yanıtı Claude'a atfetmeyiz. Yanıtlar `claude-haiku-4-5-20251001` ile, uç noktada günlük bütçe sınırlı üretilir.
usage	input / cache_read / cache_write / output token sayıları; cache çalışıp çalışmadığını buradan görebilirsin.
retrieval	`documents_sent`: istek başına gönderilen belge sayısı - her zaman tüm koleksiyon, çünkü önbellek öncü kısmının her soruda aynı kalması gerekiyor. `mode`: `filtered` ise sorudaki ayırt edici terimler öncelik listesini daralttı (en fazla 24 pasaj), `full` ise daraltacak terim bulunamadı.

Hatalar

Durum	Gövde	Ne zaman
400	`bad_request`	Gövde JSON değil.
400	`bad_question`	Soru boş veya 400 karakterden uzun.
405	`method_not_allowed`	POST dışında metod.
429	`busy`	IP başına 60 saniyede 8 istekten fazla; veya Anthropic tarafında oran sınırı.
500	`not_configured`	Uç noktanın API anahtarı yok.
200	`refused`	Claude yanıt vermeyi reddetti; gövde boş, durum 200.
502	`upstream`	Claude erişilemedi ve yedek motor da yanıtlayamadı.

Korpus ve kapsama

Kapsamı oldugu gibi yaziyoruz; Almanca diğerlerinden az.

Korpus ve kapsama

Koleksiyon	Belge	Diller
Kur'an - Bedir pasajları	41 (Âl-i İmrân 3:12, 3:121-127; Enfâl 8:1-76)	ar 111/111 · en 111/111 · tr 110/111 · de 41/111
Buhârî (Bedir/ gazve babları)	68	sunnah.com numaralandırması
Müslim	2	sunnah.com numaralandırması
Sürüm	2026-10-07	korpusun içinde `version` alanı var

Kaynaklar: Tanzil (Uthmani) ve api.alquran.cloud üzerinden Diyanet Vakfı / Saheeh International / Bubenheim & Elyas mealleri; hadisler fawazahmed0/hadith-api üzerinden, numaralandırma sunnah.com ile eşleşir. Ticari kullanım ve meal telifleri DATA_NOTES.md dosyasında tartışıldı.

Dene

Tarayıcıdan doğrudan; CORS açık.

HTTP

Sınırlar

Yanıtlar claude-haiku-4-5-20251001 ile üretilir: prompt cache sayesinde soğuk soru 30-65 bin token yazar, sıcak soru yaklaşık 130 taze token öder (ölçüldü). Uç noktanın günlük bir token bütçesi var; aştığında Claude'a hiç gitmez, yedek motor yanıtlar ve provider bunu söyler.
Bu bir demo uç noktasıdır: kimlik doğrulama yok, hız sınırı IP başınadır, SLO yoktur.
Koleksiyon Bedir Savaşı ile sınırlıdır; kapsamadığı bir soru sorulduğunda uydurmak yerine kapsamadığını söyler.
Alıntılandığında birebir alıntı quote alanındadır; ama alıntının doğruyu desteklemesi ayrı bir iştir - bu korpusla ölçümü eval/ klasöründe yazdık ama henüz koşmadık.

Bu sayfanın kodu ve korpusu: github.com/mevlanayalcin/bedir-ai