prompter API

Genel bakış

prompter küçük bir REST API sunar. Bir prompt ve bir platform gönderirsiniz, prompter o platformu çağırır ve değiştirilmemiş yanıtı döndürür. Asla özetlemez ya da veri uydurmaz: bir platform yanıt veremiyorsa yanıt bunu açıkça söyler.

Base URL

https://api.prompter.searchestra.com

Kurallar

• Tüm istek ve yanıt gövdeleri application/json'dur.
• Başarılı okumalar üst düzey bir data alanı döndürür. Hatalar üst düzey bir error alanı döndürür (bkz. Hatalar).
• Her /v1/* uç noktası X-API-Key başlığını ister. /healthz istemez.
• Zaman damgaları UTC ve ISO 8601'dir (örneğin 2026-08-16T13:47:09Z).

Hızlı başlangıç

İlk sorgunuzu gönderin. pr_your_key'i tenant'ınıza verilen API anahtarıyla değiştirin (bkz. Kimlik doğrulama).

curl -X POST https://api.prompter.searchestra.com/v1/collect \
  -H "X-API-Key: pr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "perplexity",
    "promptText": "en iyi bulaşık deterjanı hangisi, kısaca söyle",
    "countryCode": "tr",
    "language": "tr"
  }'

{
  "data": {
    "rawText": "Türkiye'de en çok tercih edilenler arasında Finish ve Fairy...",
    "rawHtml": "",
    "citations": [
      { "url": "https://example.com/inceleme", "title": "En iyi deterjan", "position": 1 }
    ],
    "textLinks": [],
    "collectedAt": "2026-08-16T13:47:09Z"
  }
}

Kimlik doğrulama

Her /v1/* isteği X-API-Key başlığında bir API anahtarı taşımalıdır. Anahtarlar pr_ önekiyle başlar ve bir kullanıcıyı değil bir tenant'ı temsil eder.

X-API-Key: pr_your_key

Sunucu yalnızca anahtarın SHA-256 hash'ini saklar. Ham değer yalnızca üretim anında bir kez gösterilir ve kurtarılamaz. Anahtar kaybolursa yeni bir tane üretin. Bir tenant birden çok anahtar tutabilir; birini iptal etmek diğerlerini etkilemez.

Bir platforma sor

Tek bir prompt'u tek bir platforma gönderir ve ham yanıtı döndürür. Akış: promptText doğrulanır, platform'un kayıtlı olduğu onaylanır, sonra gerçek bir upstream isteği yapılır.

İstek gövdesi

Yanıt data

Platformları listele

Kayıtlı platformların sabit listesini döndürür. Kimlik bilgisi yapılandırılmamış bir platform da burada görünür; yalnızca gerçek bir /v1/collect çağrısında başarısız olur. Bunu bir kez çekip kendi tarafınızda önbelleğe alın.

{
  "data": [
    { "code": "chatgpt", "unsupportedCountries": [] },
    { "code": "perplexity", "unsupportedCountries": null }
  ]
}

unsupportedCountries ya boş dizi ya da null'dur; ikisi de "kısıt yok" demektir. İkisini aynı şekilde ele alın.

Sağlık kontrolü

Konteyner orkestrasyonu için liveness probe. Kimlik doğrulama gerektirmez. Servis ayaktayken 200 döner.

Platformlar

Dokuz platformun gerçek entegrasyonu vardır. citations yalnızca üç kaynaklı platformda native'dir; altı LLM platformu linkleri textLinks üzerinden verir.

Hatalar

Hatalar bir code ve bir message içeren error nesnesi döndürür.

{ "error": { "code": "unauthorized", "message": "X-API-Key başlığı gereklidir." } }

Limitler ve kotalar

prompter dört bağımsız guard uygular. İlk ikisi API anahtarı başınadır ve 429 döner; sonraki ikisi tenant ve platform başınadır ve 422 döner; sonuncusu tüm tenant'lar için paylaşılır ve 503 döner.

Limitler planınıza göre ölçeklenir. Circuit breaker, bir platform art arda başarısız olunca açılır ve bir cooldown sonrası otomatik kapanır.