REST API

SDK, HTTPS üzerinden RDUI/1 konuşur. Bu uç noktaları kendiniz nadiren çağırırsınız; ancak bir tur ters gittiğinde cevabın bulunduğu katman burasıdır.

Temel URL: https://api.rendel.ai

Başlıklar

Her istekte gönderilir. İsim değişikliğinden önce bunlar X-NC-Key, X-NC-Device ve X-NC-User-Token şeklindeydi ve anahtarlar nc_pk_ ile başlıyordu; her iki yazım da kabul edilir ve bir nc_pk_ anahtarı çalışmaya devam eder.

Durum kodları

Aynı kodlar her uç noktada aynı anlama gelir.

Bir 404, bilerek "böyle bir kimlik yok" ve "bu kimlik size ait değil" durumları için aynı yanıttır. Herkese açık bir anahtara sahip olan bir çağırıcıya hangi kimliklerin mevcut olduğunu söylemek, başka bir kiracının kimlik alanı üzerinde bir arama kâhinliği (lookup oracle) sunmaktır.

SSE akışı açıldıktan sonra, POST /v1/chat arızaları bir HTTP durumu olarak değil, aynı kodlara sahip bir error olayı olarak akışın içinde bildirir; yanıt o zamana kadar zaten 200 olmuştur. Hata kodları sayfasına bakın.

POST /v1/chat

Ana iş yükünü üstlenen tek uç nokta. İstemci el sıkışmasına ek olarak message, form_submission, selection veya tool_results alanlarından tam olarak birini gönderin. text/event-stream döndürür.

curl -N https://api.rendel.ai/v1/chat \
  -H "X-Rendel-Key: rd_pk_test_..." \
  -H "X-Rendel-Device: 4f3c1a0b9d2e8f7a6b5c4d3e2f1a0b9c" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {"text": "Where is my order 1042?"},
    "turn_id": "3f1c2b90-8e4d-4a71-9c15-2b7e0a4d6f83",
    "client": {
      "protocol": 1,
      "sdk": "web/0.21.0",
      "catalog_version": "2026-09.a",
      "components": ["text", "quick_replies", "order_tracker", "confirm_card"],
      "actions": ["reply", "open_url", "navigate", "call", "copy", "add_to_calendar"],
      "capabilities": ["answer_pages", "detail_pages"]
    }
  }'

İstemci el sıkışması

Akış olayları

Her olay v: 1 ve monotonik bir seq taşır.

turn.end bekleyen bir durum bildirdiğinde, bekleyen çağrılar için tool_results taşıyan bir devam POST /v1/chat isteğiyle yanıt verin.

GET /v1/apps/config

Henüz init() çağırmış bir cihaz için Rendel'in yayınlanmış görünümü ve açılış yüzeyi. ETag ile önbelleğe alınır.

Buradaki her şey tasarım gereği herkese açıktır; yayınlanabilir bir anahtar bunu okuyabilir ve yayınlanabilir bir anahtar ikili dosyanızda yer alır.

Yanıt 200

{
  "channel": "published",
  "version": 7,
  "updated_at": "2026-09-01T10:12:04.000Z",
  "config": {
    "theme": { "accent": "#2E40EA", "radius": { "card": 16 } },
    "copilot": { "assistantName": "Ada", "launcherLabel": "Ask", "suggestions": ["Where is my order?"] }
  },
  "available": true
}

Yanıtlar Vary: X-Rendel-Key, X-NC-Key taşır — 200 üzerinde olduğu gibi 401 ve 403 üzerinde de; çünkü gövde tamamen bir istek başlığına bağlıdır ve yalnızca URL üzerinden anahtarlanan bir önbellek, bir kiracının markasını soran bir sonraki cihaza teslim eder.

Çıkışta doğrulamadan geçemeyen bir satır, SDK'nın okumaya çalışabileceği bir şey yerine {} olarak sunulur.

POST /v1/apps/manifest

Aksiyon manifestinizin idempotent yüklemesi. Snapshot'lar değiştirilemezdir, (app, hash) ile anahtarlanır; aynı manifesti iki kez göndermek tek bir satırı etkiler.

İstek

{
  "manifest": {
    "version": 1,
    "actions": [ … ],
    "routes": [
      {
        "name": "order_detail",
        "title": "Order",
        "description": "One order's details",
        "params": { "order_id": { "type": "string", "required": true, "fromActions": true } }
      }
    ]
  },
  "sdk": "flutter/0.44.0"
}

routes (isteğe bağlı, en fazla 50), navigate aksiyonunun açabileceği, registerRoute ile kaydedilmiş ekranlardır. name snake_case biçimindedir, en fazla 64 karakterdir. title (en fazla 60 karakter) kartın gösterdiği şeydir ve siz yazarsınız. description (en fazla 300 karakter) modele ekranı ne zaman kullanacağını söyler. params en fazla 8 parametre alır; her biri string, number veya boolean ve isteğe bağlı olarak required olabilir. fromActions olarak işaretlenmiş bir parametre, aksiyonlarınızdan birinin bu sohbette döndürdüğü bir değeri taşımalıdır. Rotası olmayan bir derleme alanı atlar ve karması değişmez.

Yanıt 200

{ "manifest_hash": "9b2f…" }

Bu karmayı her sohbet isteğinde client.manifest_hash olarak gönderin. Sunucunun görmediği bir karma, hiçbir aksiyon olmadan sunulmak yerine turu manifest_unknown ile sonlandırır — boş bir aksiyon seti, modelin uygulamanızın kesinlikle yapabileceği bir şey hakkında "Bunu yapamam" demesine yol açar.

Yanıt 400 aksiyonu ve alanı belirtir:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid action manifest: actions.1.name — snake_case action names (+2 more)",
    "details": [
      { "path": "actions.1.name", "message": "snake_case action names" },
      { "path": "actions.3.nc.timeoutMs", "message": "Too big: expected number to be <=120000" }
    ]
  }
}

details en fazla on iki sorun taşır. path, gönderdiğiniz belgenin içindeki konumdur, böylece kendi kaynak kodunuzda grep ile taranabilir.

POST /v1/identify

Cihazı bilinen bir kullanıcıya bağlar, niteliklerini kaydeder ve cihazın anonim geçmişini onların üzerine taşır. Flutter 0.13.0 sürümünden itibaren ve web'de başından beri, turların kendisi kimin oturum açtığını söyler (POST /v1/chat üzerinde user); bu çağrı yine de nitelikleri taşır.

İstek

Yanıt 200: { "end_user_id": "…", "verified": true }

verified, çağrının tüm amacıdır. Nitelikler yalnızca çağırıcı kim olduğunu kanıtladığında veya kayıt ilk başta hiç doğrulanmadığında taşınır — aksi takdirde yayınlanabilir anahtarınızı elinde tutan herhangi biri, doğrulanmış rozeti üzerinde kalırken doğrulanmış bir kullanıcının profilini yeniden yazabilirdi.

POST /v1/invocations/:id/confirm

Kullanıcının bir onay kartına verdiği, sunucunun kaydettiği yanıt. Butona basıldığı anda ve işleyiciniz çalışmadan önce çağırın, böylece kayıt işleyicinin ne yaptığından bağımsız olarak var olur. X-Rendel-Device zorunludur.

İstek: { "decision": "confirm" } veya { "decision": "decline" }

Yanıt 200: { "status": "confirmed" }, { "status": "declined" } veya { "status": "expired" }

İkinci bir çağrı, kaydedilen yanıtla birlikte { "status": "…", "already_answered": true } döndürür. İlk yanıt geçerlidir: dengesiz bir bağlantı üzerinden çift dokunma tek bir satırı bir kez değiştirir ve bir ret, bir onayın üzerine yazamaz.

Bu çağrının zorunlu olup olmadığı uygulama başınadır. Varsayılan olarak eski sözleşme hâlâ geçerlidir — confirmed: true taşıyan bir sonuç kabul edilir — çünkü bu uç noktadan önce gelen bir SDK bunu asla çağırmaz. Settings → Security → Request verification → Record confirmations on the server ayarını açın ve sunucunun kendi kaydı geçerli olan tek şey haline gelsin. Güvenlik özeti sayfasına bakın.

POST /v1/invocations/:id/edit

Kullanıcının yanıtlamadan önce bir onay kartında değiştirdiği bir değer. Yalnızca aksiyonun düzenlenebilir olarak işaretlediği parametreler değiştirilebilir (bir aksiyonun manifest içindeki nc.editable alanı, her iki SDK'da editable ile veya yönetim panelindeki bir aksiyonda Kart üzerinde değiştirilebilir ile ayarlanır). Sunucu, değişikliği önerilen parametrelerle birleştirir, tüm çağrıyı tıpkı modelinkini kontrol ettiği gibi aksiyonun şemasına göre kontrol eder, yeni değerleri yürütme için saklar ve kartı bunlarla yeniden çizer. Başlıklar /confirm ile aynıdır: X-Rendel-Key (veya X-NC-Key) ve zorunlu olan X-Rendel-Device (veya X-NC-Device).

İstek: { "params": { "quantity": 3 } }

Yanıt 200: Yeniden çizilen onay kartının özellikleri olarak { "card": { … } }. Eskisinin yerine bunu çizin. Sonrasında onaylamak, aksiyonu değiştirilen değerlerle çalıştırır.

Yanıt 422 reddedilen her değeri belirtir:

{
  "error": {
    "code": "invalid_params",
    "message": "\"quantity\" must be <= 10",
    "fields": { "quantity": "\"quantity\" must be <= 10" }
  }
}

Aksiyonun düzenlenebilir olarak işaretlemediği bir parametre, "This cannot be changed on the card." ifadesiyle aynı şekilde reddedilir.

POST /v1/feedback

Tek bir asistan turunda tek bir başparmak işareti. X-Rendel-Device zorunludur.

İstek

Yanıt 200: { "ok": true }

(message, device) ile anahtarlanır: ikinci bir çağrı bir oy eklemek yerine değerlendirmeyi değiştirir. 404, hem "böyle bir tur yok" hem de "bu tur size ait değil" durumlarını kapsar.

POST /v1/ratings

Model turu olmadan kaydedilen bir rating bloğunun yanıtı. X-Rendel-Device zorunludur.

İstek

Yanıt 200: { "ok": true }

Yanıtlar (message, block, device) ile anahtarlanır: ikinci bir çağrı puanı değiştirir ve yeni bir tane göndermedikçe önceki yorumu korur.

POST /v1/uploads

Bir kullanıcının Rendel'e verdiği, onu taşıyan turdan önce yüklenen tek bir dosya. Gövde, dosyanın baytlarıdır ve başka bir şey içermez (multipart yok). Content-Type; image/png, image/jpeg, image/webp, image/gif, application/pdf veya text/plain türlerinden biridir, en fazla 20 MB. X-Rendel-Device zorunludur. Dosya o cihaza aittir ve başka bir cihazdan kimliğini belirten bir tur, dosya olmadan yanıtlanır.

Yanıt 201: { "id": "…", "media_type": "image/png", "bytes": 48213 }

Kimliği POST /v1/chat üzerinde attachments içinde (tur başına en fazla 4) veya bir formun upload alanının değeri olarak gönderin. Bir dosya modelin önüne yalnızca onu taşıyan turda gelir ve sonraki geçmişte yeniden oynatılmaz. Bir form, yalnızca yönetim panelinde (Settings → Keys & environments) Files in forms açıldıktan sonra dosya isteyebilir.

GET /v1/apps/logo

Yapılandırmanın belirttiği logo: test anahtarı için taslak, canlı anahtar için yayınlanmış olan. Yapılandırmadaki logoAssetId değerini izleyen /v1/apps/logo?v= olarak çağırın. v önbellek anahtarı işlevi görür ve yanıt bir yıl boyunca sabittir (immutable).

POST /v1/pairings/claim

pair fonksiyonunun çağırdığı uç nokta. İstek: Yönetim panelinin gösterdiği şekilde { "code": "K7Q2-M9XD" }. X-Rendel-Device zorunludur. Yalnızca test anahtarları.

Yanıt 200: ends_at eşleştirmenin ne zaman biteceği olmak üzere { "paired": true, "ends_at": "…" }.

Bir test uygulamasını eşleştirin bölümüne bakın.

GET /v1/conversations/:id/messages

Geçmiş ve kesilen bir akıştan sonra yakınsama. X-Rendel-Device gerektirir (onsuz 400 invalid_request): bir sohbeti yalnızca onu tutan cihaz okur.

Yanıt 200

{
  "conversation_id": "…",
  "messages": [
    { "id": "…", "role": "user", "blocks": [ … ], "created_at": "…" }
  ]
}

Bloklar yer tutucu biçiminde saklanır ve çıkışta geri yüklenir, böylece kendi geçmişini isteyen cihaz, kullanıcısının yazdığı değerleri alır. Canlı bir anahtar bir test ortamı sohbetini okuyamaz ve bunun tersi de geçerlidir; başka bir uygulamadan veya başka bir cihazdan gelen bir anahtar, hata yerine boş bir liste alır çünkü ikisi de aynı yanıttır.

POST /v1/events

Toplu SDK telemetrisi. Bir olay türü tutulur: Yönetim panelinin Screens sayfasının saydığı, bir cevaptaki karttan açılan uygulamanın bir ekranı olan screen_open. Başka herhangi bir tür kabul edilir ve atılır; böylece daha yeni bir SDK daha fazlasını gönderdiği için asla reddedilmez. Faturalandırma ve kullanım sunucu kaynaklıdır ve bu uç noktaya asla güvenmez.

X-Rendel-Device gönderin; cihazı olmayan bir açılış atılır.

{
  "events": [
    { "type": "screen_open", "message_id": "7b0c3a52-…", "block_id": "blk_65475c9e", "route": "orders" }
  ]
}

Bir açılış yalnızca o cevap uygulamanıza ait olduğunda ve içindeki o blok route hedefine bir navigate taşıdığında kaydedilir; başka her şey bir hata olmadan atılır. Aynı karta ikinci bir dokunuş ikinci bir kişi değil, bir dokunuş olarak sayılır. Bir gruptan en fazla 10 açılış okunur ve bir cihaz, sohbette olduğu gibi sınırlandırılır.

Yanıt 204, boş.