İçeriğe geç
Sursa Developers

POST/v1/chat

Asistanın yanıtını akış olarak alma (SSE)

chat

Bir yük dengeleyicinin arkasında birden çok API örneği çalıştığında (api.<domain> adresi, 1.62.0), bir yanıt ve olaylarının arabelleği, yanıtı üreten örneğin belleğinde tutulur. Akışı Last-Event-ID ile sürdürmek yalnızca o örnekte çalışır.

Aynı request_id ve sohbetle yapılan ve yanıt tamamlandıktan sonra başka bir örneğe ulaşan yinelenen istek, soruyu yeniden sormadan kaydedilmiş yanıtı alır (token ve done, olaylar 1’den numaralanır). Yanıt hâlâ üretilirken başka bir örneğe ulaşan yinelenen istek, o üretimi durdurur ve yanıtı yeniden oluşturur; ikinci bir soru da oluşturulmaz. Yeni bir üretim olmadan akışı sürdürmek için bağlantıyı aynı örnekte tutun ya da isteği done olayından sonra yineleyin.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

  • X-View-Asstring

    Yalnızca admin rolündeki API anahtarları için. İsteği <profile>[:viewer|verifier|editor] veri profili adına yapar, örneğin employee:viewer. Kurulum anahtarı bu başlığı kullanamaz (403).

Çerez parametreleri

  • kb_view_asstring

    Bir oturum için “View as” modunun (başka bir kullanıcı gibi görüntüleme) çerezi. POST /auth/view-as bu çerezi ayarlar, DELETE /auth/view-as temizler.

İstek gövdesi

application/json

Nesne: ChatRequest

  • messagesarray of ChatMessagezorunlu

    items ≥ 1

  • collectionstring

    Varsayılan: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    Varsayılan: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Yanıtı yanıt önbelleğinden almaz (önbellekteki yanıtın altındaki “Get a fresh answer” (yeni yanıt al) düğmesi). Yeni yanıt, önbellekteki kaydın yerini alır.

    Varsayılan: false

  • languagestring | null

    Yanıt dili: o dilde yanıt almak için bir ISO 639-1 kodu (de, en, ru, …). auto ile ya da alan olmadan dil sorudan algılanır. Arayüz, başka bir dildeki önerinin dilini açıkça gönderir (Starter.language).

  • scopeChatScope | null

    Sorunun alanı: birkaç koleksiyon, bir kaynak, etiketler ve bir dönem. Soru alanındaki koleksiyonlar collection yerine geçer. Kaynak, yanıtı kendi koleksiyonuyla (ve kendi kartlarıyla) daraltır. Etiketler tags listesine eklenir. Dönem, finansal yanıtları o dönemle sınırlar. Yalnızca kullanıcının görebildiklerini seçebilirsiniz (koleksiyonlar: collections.no_access/collections.not_found; kaynak: sources.not_found). conversation_id ile soru alanı sohbete kaydedilir. Bu alan gönderilmezse sohbete kayıtlı soru alanı uygulanır; null ya da boş bir soru alanı onu temizler.

  • request_idstring

    Sorunun idempotency anahtarı. Bir sorunun akışını her yeniden denemede aynı anahtarı gönderin (bağlantı koptuktan sonra yeniden deneme; burada Last-Event-ID akışı sürdürmez, yalnızca günlüğe yazılır). Kaydedilmiş bir yanıtın anahtarıyla yapılan yeniden deneme ikinci bir soru oluşturmaz: soru ya da kredi sınırı dolmuş olsa bile kaydedilmiş sonuç tek bir done olayı (ve metinle birlikte bir token) olarak yeniden gönderilir. Önceki yanıt, bağlantısı kopan bir istemci için hâlâ hazırlanıyorsa bu hazırlık durur ve yanıt yeniden oluşturulur.

    length ≤ 64

  • version_ofinteger (int64)

    Bu sorunun sohbetteki turunun yeni bir sürümünü oluşturur (sohbet geçmişindeki question_id): düzenlenmiş bir soru (messages içinde yeni metin), yeniden oluşturulmuş bir yanıt (aynı metin, genellikle bypass_cache ile) ya da başka bir quality ile aynı soru (örneğin precise, bir fast yanıtından sonra). Önceki soru-yanıt çifti korunur. Ondan sonraki turlar kendi dalında kalır ve yeni sürüm seçiliyken sohbet geçmişinde gizlenir (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Yanıt için kullanılan geçmiş, bu tura kadar seçili daldır. Bir sürümün quality değeri sohbetin ayarlarını değiştirmez. conversation_id gerektirir; başka bir sohbetten bir soru 404 questions.not_found döndürür.

  • qualitystring

    Sonucun arkasındaki aramada hız ile doğruluk arasındaki denge: fast daha hızlı, precise daha doğrudur. Varsayılan: precise.

    Geçerli değerler: fastprecise

Yanıtlar

200`stream=true` ile: `text/event-stream`. Her olay `id: <number>` (olayın akıştaki sıra numarası, 1’den başlar) ve `data: <JSON>` satırlarından ve ardından gelen boş bir satırdan oluşur. `event:` ve `retry:` alanları kullanılmaz; olay türü `type` alanındadır (`ChatEvent`).

stream=true ile: text/event-stream. Her olay id: <number> (olayın akıştaki sıra numarası, 1’den başlar) ve data: <JSON> satırlarından ve ardından gelen boş bir satırdan oluşur. event: ve retry: alanları kullanılmaz; olay türü type alanındadır (ChatEvent).

request_id içeren bir soru bağlantıdan bağımsız olarak yanıtlanır. Bağlantının kopması yanıtı durdurmaz: yanıt tamamlanır ve sohbete kaydedilir (en fazla 10 dakika boyunca). Aynı isteği (aynı request_id ve sohbet) yinelemek süren yanıta bağlanır; Last-Event-ID başlığıyla o numaradan sonraki olayları alır, böylece akış aynı olay numaralarıyla devam eder. Akış o numaradan devam edemiyorsa yinelenen istek akışı baştan alır: bu durumda ilk olayın numarası Last-Event-ID değerinden büyük değildir ve istemci yanıtı baştan başlatır. Yanıt zaten tamamlanmış ve olay arabelleği serbest bırakılmışsa (3 dakika sonra) kaydedilmiş sonuç, soru yeniden sorulmadan tekrar gönderilir (token ve done, 1’den numaralanır); aksi hâlde yanıt yeniden üretilir. Böyle bir yanıtı durdurmak için POST /v1/chat/cancel çağırın. request_id olmadan istemci bağlantısının kopması yanıtı iptal eder.

İlk olaydan sonra, yanıt sürerken sunucu her 15 saniyede bir : ping yorumu gönderir; bunu atlayın. Olay sırası: stage olayları (ilerleme), meta, sources, data, ardından token olaylarında yanıt metni, sonra done. Yanıt metninden önce sources ve data tekrarlanabilir ve tool olayları görünebilir; metin tek bir token olarak ya da parçalar hâlinde gelebilir. Önbellekteki bir yanıt: meta (cached ile), sources, data, token, done. Akış başladıktan sonraki bir hata error olayı olarak gelir ve akış done olmadan kapanır; akışın HTTP durumu her zaman 200’dür. done olayından sonra önerilen sonraki soruları içeren bir followups olayı gelebilir. İşlemediğiniz olay türlerini yok sayın.

stream=false ile: AnswerResponse gövdeli application/json (ayrıca conversation_id).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

text/event-stream

Nesne: ChatEvent

Şunlardan biri

application/json

Nesne: AnswerResponse

  • answerstringzorunlu
  • question_idintegerzorunlu
  • querystring
  • collectionstringzorunlu
  • sourcesarray of Sourcezorunlu
  • table_queriesarray of TableQueryzorunlu
  • datasetsarray of Datasetzorunlu
  • chartsarray of ChartSpeczorunlu
  • warningsarray of AnswerWarningzorunlu
  • timingsTimingszorunlu
  • provenancearray of NumberProvenance
  • emptystring

    Geçerli değerler: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    Bu yanıt için araçların neden kullanıldığı: request (açıkça istendi); compare, compute, action (soruya göre); needs_calc (tablolar üzerinde hesaplama gerekiyor); summary (bir koleksiyonun ya da belgelerin genel görünümü); mcp (kuruluş harici MCP sunucularını bağlamış).

    Geçerli değerler: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityzorunlu
  • followupsarray of Followupzorunlu
  • conversation_idstring

    Yalnızca sohbetli POST /v1/chat için.

  • answer_idstring

    Yanıt nesnesinin kimliği.

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

404Nesne yok ya da size açık değil. API, erişimi kısıtlı bir nesnenin var olduğunu belli etmez.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

  • Retry-After

    İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← answers · API başvurusu