API'ye genel bakış

Peki API, kendi yazılımınızın agent'larınızla konuşmasını sağlar. Agent'ınızı uygulamanızın sohbet ekranına koyabilir, CRM'inizden ona mesaj gönderebilir, mağazanıza sipariş geldiğinde bir otomasyon başlatabilir ya da bir agent'ın üzerine kendi web sitesi sohbetinizi kurabilirsiniz. Bu sayfa haritadır; her yüzeyin kendi sayfası var.

Temel adres

https://peki.ai/api

Bu dokümanlardaki her yol bu adrese göredir. Örneğin POST /agents/{agentId}/sessions şu anlama gelir:

POST https://peki.ai/api/agents/{agentId}/sessions

Tek istisna gelen webhook'lardır; onların kendi tam adresi vardır (aşağıya bakın).

Herkese açık API yüzeyleri

Yüzey	Ne işe yarar	Kimlik doğrulama	Sayfa
Sessions API	Kendi uygulamanızdan sohbetler: her kullanıcı için oturum başlatın, mesaj gönderin, cevapları akış olarak alın, dosya yükleyin, puan verin ve çözüldü olarak kapatın.	API anahtarı	Sessions API
Dosyalar	Bir konuşmadaki dosyayı indirin: müşterinin fotoğrafı, bir belge, ekibinizin cevabındaki ek.	API anahtarı	Dosyalar
Gelen webhook'lar	Başka bir sistemin (Stripe, Shopify, GitHub, bir form) orada bir şey olduğu anda otomasyon başlatmasını sağlayın.	Gizli webhook URL'si, isteğe bağlı olarak imza	Gelen webhook'lar
Web sitesi sohbeti API'si	Web sitesi sohbetinin arkasındaki herkese açık uç noktalar; tarayıcıda kendi sohbet arayüzünüzü kurmak için.	Widget'ın herkese açık anahtarı ve bir ziyaretçi kimliği	Web sitesi sohbeti API'si

not

API anahtarları Peki panelinin kendisinin kullandığı API'ye erişir, ancak yalnızca burada belgelenen uç noktalar herkese açık API'dir. Diğer uç noktalar Peki panelinin kendi ekranları için yapılmıştır ve haber verilmeden değişebilir. Yalnızca burada belgelenenlerin üzerine kurun.

Başlamadan önce

1. Agent'ınızı yayınlayın. Müşteriler de API çağrılarınız da her zaman yayındaki sürümle konuşur. Yayınlamak ücretli plan gerektirir. Bkz. Yayınlama ve sürümler.
2. Bir API anahtarı oluşturun: Ayarlar → API anahtarları (yöneticiler). Mesaj göndermek için Okuma ve yazma, yalnızca okumak için Yalnızca okuma seçin. Bkz. API anahtarları.
3. Agent'ınızın kimliğini bulun. Agent'ı Peki panelinde açın; kimlik, adreste /agents/ sonrasındaki kısımdır. https://peki.ai/agents/66f1c2a9e4b0a1d2c3e4f567/instructions adresinde kimlik 66f1c2a9e4b0a1d2c3e4f567'dir.

Ardından ilk çağrınızı yapın:

curl https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions \
  -H "Authorization: Bearer psk_anahtariniz" \
  -H "Content-Type: application/json" \
  -d '{"customer": {"id": "user-1042", "name": "Ayşe Yılmaz"}}'

Kurallar

İstekler

• JSON gövdeleri Content-Type: application/json ile gönderin; dosya yüklemeleri bunun dışındadır, onlar multipart/form-data'dır.
• Kimlikler 24 karakterlik onaltılık (hex) metinlerdir, ör. 66f1c2a9e4b0a1d2c3e4f567.
• Gövdedeki bilinmeyen alanlar yok sayılır; bir sayfa gövdenin katı (strict) olduğunu söylüyorsa bu geçerli değildir.

Yanıtlar

• Yanıtlar JSON'dur; dosya indirmeleri ve akışlar bunun dışındadır.
• Zamanlar UTC'de ISO 8601 biçimindedir, ör. 2026-10-26T14:03:11.520Z.
• Değeri olmayan isteğe bağlı alanlar null olarak gönderilmez, hiç yer almaz.

Hatalar

Hatalar HTTP durum kodlarıyla ve insanın okuyabileceği bir message içeren JSON gövdesiyle döner. Bazı hatalara makinenin okuyabileceği bir code eklenir; varsa code'a bakın, çünkü message metni değişebilir.

Doğrulama hatası, neyin yanlış olduğunu issues içinde listeler (burada kısaltılmıştır):

{
  "message": "Invalid body",
  "issues": [
    { "path": ["customer", "id"], "message": "Too small: expected string to have >=1 characters" }
  ]
}

Tipik başka bir hata:

{ "statusCode": 404, "message": "Session not found", "error": "Not Found" }

Durum	Anlamı
400	İstek bozuk ya da bir alan geçersiz.
401	Kimlik bilgisi yok ya da anahtar geçersiz veya iptal edilmiş.
402	Kredi ya da plan: credits_exhausted veya plan_required.
403	Anahtarın bu işlem için gereken erişimi yok ya da uç nokta yalnızca kişiler içindir.
404	Aradığınız şey çalışma alanınızda yok.
409	İstek mevcut durumla çelişiyor, ör. agent yayınlanmamış.
413	Dosya ya da gövde çok büyük.
429	Çok fazla istek. Bekleyip tekrar deneyin.
503	İsteği şu an kabul edemedik. Biraz sonra tekrar deneyin.

Yeniden denemeler

429 ve 503 hatalarını giderek artan bir beklemeyle yeniden deneyin (ör. 1 sn, 2 sn, 4 sn). 429 dışındaki 4xx hatalarını isteği değiştirmeden yeniden denemeyin.

Maliyeti

API üzerinden başlattığınız oturumlardaki agent cevapları, diğer kanallardaki cevaplar gibi kredi harcar ve kullanımınızda Agent cevapları olarak görünür. Yayındaki cevaplar kredi yüzünden asla reddedilmez. Bkz. Planlar ve kredi.

İlgili sayfalar

• Kimlik doğrulama
• Sessions API
• Dosyalar
• Gelen webhook'lar
• Web sitesi sohbeti API'si
• API anahtarları