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. prsk_your_key'i run iznini taşıyan bir anahtarla değiştirin (bkz. Kimlik doğrulama).

curl -X POST https://api.prompter.searchestra.com/v1/collect \
  -H "X-API-Key: prsk_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. İki tür anahtar vardır; her birinin kendi öneki bulunur.

X-API-Key: prsk_your_key

Kapsam

Her anahtar tam olarak tek bir kaynağa kapsanır: bir tenant, bir workspace ya da bir project. Anahtar yalnızca o kaynağın içinde iş yapabilir. Bir project anahtarı başka bir project'e dokunamaz; bir workspace anahtarı kendi workspace'inin dışına çıkamaz.

İzinler

Her anahtar açık bir izin kümesi taşır. Bugün üç izin vardır; her uç hangisini istediğini belirtir.

User anahtarında izinler ayrıca o kişinin kapsamdaki rolüyle sınırlanır. Bir izleyiciye manage vermek yine de yönetemeyen, run vermek yine de çalıştıramayan bir anahtar üretir.

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 kaynak birden çok anahtar tutabilir; birini iptal etmek diğerlerini etkilemez. Anahtarlar isteğe bağlı bir son kullanma tarihi de taşıyabilir.

Bir platforma sor

Tek-çağrı kısayolu: tek bir platforma, bir proje altında, tek soru sorar ve saklanan çalıştırmayı döndürür. İçeride promptu kaydeder (projede aynı metin varsa onu yeniden kullanır) ve çalıştırır; böylece yanıt gerçek maliyetiyle saklanır ve projeye atfedilir. prompt kaydet + çalıştır adımlarının kolaylık sarmalayıcısıdır.

İstek gövdesi

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

Yanıt data (tek çalıştırma)

Tek bir saklanan çalıştırma döner: id, promptId, projectId, platform, status (ok/error), answerText, citations, textLinks ve gerçek maliyet alanları (costEstimate, model, inputTokens, outputTokens).

{
  "data": {
    "id": "run_…", "promptId": "prm_…", "projectId": "prj_…", "platform": "perplexity",
    "status": "ok", "answerText": "Türkiye'de en çok tercih edilenler arasında Finish ve Fairy…",
    "citations": [ { "url": "https://example.com/inceleme", "title": "En iyi deterjan", "position": 1 } ],
    "textLinks": [], "costEstimate": 0.0041, "model": "sonar", "createdAt": "2026-08-31T13:47:09Z"
  }
}

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.

Projeler

Bir proje, markanızı bir pazarla (ülke ve dil) eşler; promptlar ve çalıştırmalar onun altında yaşar. Bu uçlar bir makine anahtarının proje yönetmesini sağlar, böylece markaları kendi sistemlerinizden hazırlayabilirsiniz. Hem panel oturumunu (JWT) hem bir API anahtarını kabul ederler.

Projeleri listele

Bir workspace'in projelerini listeler. read izni ve kapsamı workspace'i kapsayan bir anahtar (tenant ya da o workspace) gerekir.

{
  "data": [
    { "id": "prj_…", "workspaceId": "wsp_…", "name": "Acme", "slug": "acme", "countryCode": "tr", "language": "tr" }
  ]
}

Proje oluştur

Bir workspace altında proje oluşturur. manage izni ve tenant- ya da workspace-kapsamlı bir anahtar gerekir (project-kapsamlı anahtar oluşturamaz, 403 forbidden alır).

İstek gövdesi

curl -X POST https://api.prompter.searchestra.com/v1/workspaces/wsp_123/projects \
  -H "X-API-Key: prsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "countryCode": "tr", "language": "tr" }'

{
  "data": { "id": "prj_…", "workspaceId": "wsp_123", "name": "Acme", "slug": "acme", "countryCode": "tr", "language": "tr" }
}

Proje güncelle

Bir projeyi yeniden adlandırır ya da pazarını değiştirir. manage izni ve kapsamı projeyi kapsayan bir anahtar (tenant, workspace'i ya da o proje) gerekir. Gövde alanları oluşturmayla aynı ama hepsi opsiyonel: yalnızca değişeni gönder, gönderilmeyen alan olduğu gibi kalır. Gönderilen alan oluşturmadaki gibi doğrulanır; boş string alanı silmez, reddedilir.

Pazar (countryCode ve language), projede ilk çalıştırma yapıldıktan sonra kilitlenir; böylece geçmiş sonuçlar tek bir pazara ait kalır. Bundan sonra değiştirmek 409 conflict döner. Başka bir pazarı ölçmek için yeni proje oluştur.

Proje sil

Projeyi ve altındaki her şeyi (promptlar, çalıştırmalar ve kapsamlı anahtarlar cascade) siler. manage izni ve kapsamı projeyi kapsayan bir anahtar gerekir. Geri alınamaz.

Promptlar ve çalıştırmalar

Bu uçlar kalıcı çalıştırma kanalıdır: bir promptu proje altında saklar, platformlarda çalıştırır, yanıt gerçek maliyetiyle saklanır ve projeye atfedilir. Bu, panelin kullandığı yüzeyin aynısıdır; yani bir makine anahtarı, bir kişinin uygulamada yaptığının aynısını yapar. Hiçbir şey kaydetmeyen, stateless olan /v1/collect'in muadilidir.

Promptları listele

Bir projedeki kayıtlı promptları listeler. read gerekir.

Prompt oluştur

Bir proje altına prompt kaydeder. manage gerekir.

{ "data": { "id": "prm_…", "projectId": "prj_…", "text": "girişimler için en iyi crm", "createdAt": "2026-08-31T12:00:00Z" } }

Prompt çalıştır

Kayıtlı bir promptu seçilen platformlarda canlı istekler olarak çalıştırır. Proje (ve ülke/dil) prompttan alınır. Her platform bağımsızdır: biri başarısız olsa diğerleri sürer. Her sonuç gerçek maliyetiyle bir çalıştırma olarak saklanır. run gerekir.

curl -X POST https://api.prompter.searchestra.com/v1/prompts/prm_123/run \
  -H "X-API-Key: prsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "platforms": ["chatgpt", "perplexity"] }'

{
  "data": [
    { "id": "run_…", "promptId": "prm_123", "platform": "chatgpt", "status": "ok",
      "answerText": "…", "citations": [], "textLinks": [],
      "costEstimate": 0.0037, "model": "gpt-4o", "inputTokens": 812, "outputTokens": 143,
      "createdAt": "2026-08-31T12:00:05Z" }
  ]
}

status platform başına ok ya da error'dur (kısmi başarı). Başarısız platform errorMessage taşır ve maliyeti sıfırdır.

Bir promptun çalıştırmalarını listele

Bir promptun çalıştırma geçmişini, en yeni önce döner. read gerekir.

Proje kullanımı

Projenin gerçek maliyetini saklanan çalıştırmalardan toplar; toplam ve platform bazında. read gerekir. (GET /v1/projects/{projectId}/overview aynı kullanımı artı prompt sayısı ve son çalıştırmaları döner.)

{
  "data": { "totalRuns": 42, "totalCostUsd": 0.1873,
    "byPlatform": [ { "platform": "chatgpt", "runs": 20, "costUsd": 0.09 } ] }
}

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 beş bağımsız guard uygular. Hız ve eşzamanlılık guard'ları YALNIZCA gerçek para harcayan çalıştırma uçlarına (POST /v1/collect ve POST /v1/prompts/{promptId}/run) uygulanır; listeleme, oluşturma ve okuma muaftır.

Hız ve eşzamanlılık guard'ları kimlik bazlıdır: makine çağrısı anahtarına, panel çağrısı kullanıcısına göre. Bir anahtar sınırlanınca tenant'ın diğer anahtarları/kullanıcıları etkilenmez. 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.