Setup API

Yapay zeka kodlama aracınızın çalıştırdığı kurulum dosyası, bu API'nin istemcilerinden biridir. Bu sayfaya yalnızca başka bir istemci yazıyorsanız ihtiyaç duyarsınız: kendi yapay zeka kodlama aracınız, bir betik, bir CI işi. Buradaki her şey, kurulum dosyasının bizzat dayandığı unsurlardır ve sunucu her istemciyi aynı kurallara tabi tutar.

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

Bu, api.rendel.ai adresindeki SDK API'si değildir (bkz. REST API). Kurulum API'si, yönetim panelinin yazdıklarını yazar; bu nedenle yönetim panelinin yanında çalışır ve yönetim panelinin kendi kontrollerini uygular.

Kimlik doğrulama

GET /file dışındaki her uç nokta oturumun kurulum belirtecini alır ve yalnızca bu üstbilgide kabul eder:

Authorization: Bearer rd_st_0123456789abcdef01234567

Bir belirteç, rd_st_ ve 24 küçük harfli hex karakterden oluşur. Yalnızca yönetim panelinin sunduğu dosyada bulunur ve başka hiçbir yerde yer almaz: Rendel yalnızca karmasını saklar. Sorgu dizesindeki bir belirteç okunmaz, dolayısıyla bir erişim günlüğüne asla girmez.

İki tür oturum vardır. Canlıya alınmış bir uygulamada kurulum oturumu (rendel-setup.md) reddedilir. Senkronizasyon oturumu (rendel-sync.md) ise reddedilmez, ancak canlıdaki bir uygulamada yazma işlemleri öneri haline gelir: proposed ile 202 yanıtı verirler ve yönetim panelinde bir kişiyi beklerler. GET /context, session.writes olarak hangisinin geçerli olduğunu belirtir: apply veya propose. Yönetim panelinde belirtilmişse geliştiricinin neyin değiştiğine dair kendi cümlesi, API'de değil, yapıştırdıkları komut istemindedir: senkronizasyon bu değişiklikle başlar.

Sınırlar

Hatalar

Her hata, SDK API'si ile aynı olan tek bir biçime sahiptir:

{ "error": { "code": "invalid_body", "message": "items.0.content: Required" } }

message, bir kişinin veya yapay zeka kodlama aracının adım atabileceği bir cümledir ve hatalı bir gövde için alanın adını belirtir. code, koşullara göre dallanma yapılacak değerdir.

Adımlar

Overview panelinde bu sırayla on üç adım bulunur. Bir adımı kimin kapattığı, bir yapay zeka kodlama aracının kendi raporunun ne yapabileceğini belirler: bir sunucu adımı için yalnızca Rendel'in gördüğü bir durum onu işaretler; yapay zeka kodlama aracının done demesi kaydedilir ancak hiçbir şeyi değiştirmez.

Yazma işlemi yapan her uç nokta kendi adımını bildirir: bir adıma yapılan ilk yazma işlemi onu başlatıldı olarak işaretler ve her yazma işlemi ne yaptığını belirten bir satır ekler. Bir yazma adımı, yapay zeka kodlama aracı daha sonraki bir adıma geçtiğinde tamamlanmış sayılır. Bu nedenle bir yapay zeka kodlama aracı POST /events uç noktasına yalnızca kod içinde gerçekleşen adımlar (discover, install, identity, verify) ve bir adımı skipped veya failed olarak işaretlemek için ihtiyaç duyar.

GET /file

GET /file?code=<32 hex> — belirteç gerektirmez. Bu, yönetim panelinin curl satırıdır:

curl -fsSL "https://rendel.ai/api/setup/file?code=<code>" -o rendel-setup.md

Dosyayı, içinde yeni üretilmiş bir belirteçle birlikte text/markdown olarak yanıtlar. Kod bir kez ve 15 dakika boyunca çalışır; ardından 410 yanıtı verir. Yönetim panelindeki Download butonu da aynı dosyayı oluşturur.

POST /start

Oturumu sahiplenir. Panel, Waiting for your agent durumundan Agent connected durumuna geçer.

{ "ok": true, "session": { "id": "…", "kind": "setup", "status": "running", "expires_at": "…" }, "app": { "id": "…", "name": "…" }, "next": "GET /context" }

Aynı tool, model ve os ile tekrar çağırmak bir yeniden başlatmadır ve aynı yanıtı verir. Farklı bir yapay zeka kodlama aracı 409 already_claimed alır.

GET /context

Yapay zeka kodlama aracının koda dokunmadan önce ihtiyaç duyduğu veriler. Salt okunur.

POST /events

Yapay zeka kodlama aracının kendi ilerlemesi. Tek bir olay, en fazla 50 ögelik bir dizi veya { "events": [...], "detected": {...} }.

Keşif raporu olan detected, şunlardan herhangi birini alabilir: platform, framework, router, http, auth, locales (en fazla 40), screens ve apiCalls (sayılar), themeFile, darkTheme (boolean), fonts (en fazla 10), logoFile, signIn, signUp. Mevcut olanla birleştirilir ve uygulama ile birlikte saklanır.

signIn, bir hesap ve parola aldığında uygulamanın kendi API'sindeki oturum açma işlemidir. signUp, bir kullanıcı oluşturan istektir. Her biri en fazla 12 alan içeren { "url": "https://…", "fields": [{ "name": "email", "secret": false, "required": true, "type": "string", "format": "email" }] } biçimindedir. Yalnızca name zorunludur; required varsayılan olarak true değerini alır. Yalnızca alan adlarını taşırlar, asla bir değer içermezler. Test sayfası, hiçbir API belgesi bunları açıklamadığında, bir test kullanıcısı olarak oturum açmak ve bir test kullanıcısı oluşturmak için bunları kullanır.

{ "accepted": 2, "ids": [101, 102], "detected": true }

PUT /appearance

Tema, taslak içine yazılır. Kurulum belirteci hiçbir zaman yayımlama yapmaz.

Tema, daha önce yüklenmiş bir logoyu koruyarak taslağın temasının yerine geçer. Asistanın adı, karşılama mesajı ve öneriler bu uç noktanın değil, Experience bölümünün konusudur.

{ "saved": true, "changed": true, "draft": true, "warnings": [
  { "check": "Body text on the surface", "what": "prose and titles", "ratio": 3.9, "minimum": 4.5, "fix": { "token": "onSurface", "suggested": "#2B2B2B" } }
] }

warnings, açık ve koyu modda (koyu moddaki bir belirteç themeDark. adını alır) minimum kontrastı karşılamayan her renk çiftini ve uygun olduğunda geçerli olabilecek aynı tonda bir değeri listeler. Bunlar uyarıdır, ret değildir: SDK, cihazdaki okunaksız mürekkep rengini her iki durumda da koyulaştırır. Önerileri uygulayın ve tekrar gönderin.

POST /logo

Multipart form verisi, dosya file adlı bir alanda yer alır:

curl -X POST "https://rendel.ai/api/setup/logo" \
  -H "Authorization: Bearer $RENDEL_TOKEN" \
  -F "file=@assets/images/logo.svg"

PNG, JPEG, WebP veya SVG, en fazla 2 MB. Yönetim panelinin bir logoyu sakladığı yerde saklanır ve taslak temada ayarlanır.

{ "saved": true, "draft": true, "logoAssetId": "…" }

PUT /experience

Asistan, taslak persona içine yazılır. Bir yamadır: dışarıda bırakılan alanlar değerlerini korur.

{ "saved": true, "draft": true, "personaVersion": 3, "changed": true }

POST /knowledge

En fazla 25 öge, { "items": [...] }. Her biri external_key değerine göre (en fazla 200 karakter) eklenir veya güncellenir; bu sayede bir anahtarın tekrar gönderilmesi ilgili kaynağı günceller.

Bir bağlantıyı, yönetim panelinde eklenen bir bağlantıyla aynı koruma mekanizmasından geçirerek Rendel'in sunucusu getirir; istemci yalnızca adresi gönderir. Arşivleme, bir kaynağı silmeden kullanım dışı bırakır. Yeni ve değiştirilen metinler hemen dizine eklenir.

{ "created": 2, "updated": 0, "unchanged": 1, "archived": 0, "failed": 0,
  "results": [{ "external_key": "plans", "ok": true, "op": "created", "id": "…", "chunks": 3 }],
  "note": "…" }

Bir ögenin başarısız olması diğerlerini başarısız kılmaz. Yalnızca hiçbiri kaydedilmediğinde yanıt 422 olur.

POST /actions

external_key değerine göre eklenen veya güncellenen ve yönetim panelinin kendi kurallarıyla denetlenen en fazla 50 HTTP aksiyonu, { "items": [...] }.

Bir arşiv ögesi { "op": "archive", "external_key": "…" } biçimindedir.

Gizli bilginin girilebileceği bir alan yoktur. Paylaşılan bir anahtar isteyen uç nokta bunu needs_key içinde belirtir (anahtarın türü ve nereye gideceği, asla anahtarın kendisi değil) ve bir kişi Add key ile bu bilgiyi girene kadar kapalı olarak kaydedilir; girildiğinde ise uç noktanın ana makinesi için bir paylaşılan anahtar haline gelir.

• auth: "none" olduğunda, paylaşılan anahtar tek kimlik bilgisidir ve aksiyon yalnızca okuma yapabilir.
• auth: "user" olduğunda, oturum açmış kişinin belirtecinin yanında gönderilir: uygulamanın anahtarını ve kullanıcının oturumunu birlikte isteyen bir API'nin yapısı. Aksiyon okuma veya yazma yapabilir. Anahtar, belirtecin gittiği yere gitmemelidir: bir bearer anahtarı, belirtecin auth_name (header:X-Auth-Token) ile taşınmasını gerektirir ve bir header anahtarı, belirtecin üstbilgisini adlandıramaz. Böyle bir öge bir gerekçeyle reddedilir.

Veriyi değiştiren her şey auth: "user" gerektirir. Böyle bir aksiyonda, bir parametredeki "editable": true değeri, kullanıcının onaylamadan önce onay kartı üzerinde bu değeri değiştirmesine olanak tanır: bir miktar, bir not, birkaç seçenekten biri. Asla bir kimlik veya uygulamanın hesapladığı bir tutar olamaz. Düzenlenebilir bir parametreye sahip read aksiyonu reddedilir, çünkü okuma işleminin kartı yoktur. Bir aksiyonda bir kişinin daha önce girmiş olduğu anahtar, aksiyon tekrar gönderildiğinde korunur ve halihazırda paylaşılan bir anahtara sahip olan bir aksiyon yeniden anahtar bekleme durumuna alınmaz.

{ "external_key": "GET /v1/pets", "name": "my_pets", "description": "The signed-in person's pets.",
  "method": "GET", "url_template": "https://api.example.com/v1/pets",
  "auth": "user", "needs_key": { "kind": "header", "name": "X-App-Key" } }

{ "failed": 0, "needs_key": ["find_stores"],
  "results": [{ "external_key": "GET /v1/stores", "ok": true, "name": "find_stores", "needs_key": true }] }

POST /screens

İstemcinin kodda registerRoute ile kaydettiği ekranları tanımlar. Bir tanımlama bir plandır: yönetim paneli, bir derlemenin manifestosu bunları adlandırana kadar bu ekranları planned olarak gösterir.

{
  "screens": [{
    "name": "order_detail",
    "title": "Orders › Order",
    "description": "One order: its items, delivery status and payment.",
    "params": { "order_id": { "type": "string", "required": true, "fromActions": true } },
    "file": "lib/rendel/routes.dart",
    "deep_link": "/orders/:id"
  }],
  "archive": [{ "name": "old_settings", "reason": "Removed in 2.3" }]
}

name snake_case biçimindedir; title 1–60 karakter; description 1–300 karakter; parametreler registerRoute içindeki gibidir. Aynı adla yeniden tanımlandığında ekran güncellenir.

{ "planned": 2, "added": 1, "updated": 0, "unchanged": 1, "archived": 1, "unknown": [], "note": "…" }

GET /status

Kimin ne bildirdiğinden bağımsız olarak Rendel'in gördükleri. Kurulum dosyası beklerken bunu sorgular.

POST /smoke

Gövde içermez. Rendel, test tarafı üzerinden uygulamanın kendi yapılandırmasından (önerileri, bilgi tabanı, bir okuma aksiyonu) derlenen üç ila beş soruyu Rendel'e sorar ve her yanıtı değerlendirir: bilgiyi kullandıysa grounded, bir aksiyon çağırdıysa action-backed. En az %80'i bunlardan biri veya diğeri olduğunda geçer. 150 saniyeye kadar süre tanıyın.

{ "id": "…", "passed": true, "createdAt": "…", "platformFailure": false,
  "results": [{ "question": "Where is my order?", "from": "suggestion", "answer": "…", "actions": ["get_order"], "grounded": false, "actionBacked": true, "ok": true }] }

Zayıf bir yanıttan ziyade her yanıt Rendel tarafında bir hata olduğunda platformFailure true olur. Yapılandırmadaki hiçbir şey bu sonucu değiştirmeyeceğinden hiçbir şeyi değiştirmeyin ve daha sonra tekrar çalıştırın.

Son çalıştırma, Go live kontrolünün okuduğu değerdir. Yönetim panelindeki Run smoke test butonu, aynı testi bir belirteç olmadan çalıştırır.

GET /smoke

Bu yanıtı kaybeden bir istemci için, POST /smoke yanıtının biçiminde en son çalıştırma. Hiçbir şey çalıştırmaz. İlk çalıştırmadan önce { "run": null } yanıtını verir.

POST /complete

Oturumu sonlandırır. Belirteç çalışmayı durdurur.

{ "ok": true, "status": "completed", "token": "revoked" }

POST /fail

İstemci devam edemiyor. Belirttiği adım (veya bir olaya sahip en son adım) panelde gerekçesiyle birlikte kırmızıya döner ve oturum sona erer.

{ "ok": true, "status": "failed", "token": "revoked" }

Kurulum dosyası ve içe aktarımı

rendel/setup.json, bir uygulamayı JSON Schema'sında (SetupFileV1) belirtildiği şekilde tek bir belgede açıklar: her bir ögesi external_key ile anahtarlanmış appearance, experience, knowledge, ekranlar ve aksiyonlar. Bir yapay zeka kodlama aracı bunu dosya yoluna yazar; bir insan da bunu elle yazabilir.

POST /api/setup/import
Authorization: Bearer <import code>
Content-Type: multipart/form-data

İçe aktarma kodu (32 hex karakteri), komutla birlikte Overview ekranından gelir; kurulum oturumu açıkken en fazla 24 saat boyunca çalışır ve tamamlanan bir içe aktarma işlemi oturumu kapatır. İstek günlüklerinin dışında kalması için URL'de değil, Authorization üstbilgisinde gönderin. Eski ?code=<import code> biçimi bir sürüm boyunca daha kabul edilecek, ardından kaldırılacaktır. Dosyayı Overview ekranının bekleme adımına veya Sync iletişim kutusuna bırakmak, oturum açılmış bir oturumdan aynı işi yapar.

Herhangi bir şey yazılmadan önce tüm dosya ayrıştırılır ve kimlik bilgileri açısından taranır; bu sayede reddedilen bir dosya hiçbir şeyi değiştirmez. Ardından her bölüm, bir yapay zeka kodlama aracının çağıracağı sırayla kendi Setup API işlemi olarak çalışır. Bir dosya, ilk olarak içe aktarılan büyük bir bilgi tabanı için yalnızca $schema, version, app ve knowledge içerebilir; tam bir dosya ayrıca summary alanına da ihtiyaç duyar. Aynı dosyayı tekrar içe aktarmak güvenlidir: her yazma işlemi external_key ile eşgüçlüdür.

200, { ok, kind, mode, file, sections, warnings } yanıtını verir: mode, applied veya canlı bir uygulamada her yazma işleminin Sync review içinde bir öneri haline geldiği proposed değeridir; file, full veya knowledge değeridir.

Her hata { error: { code, message } } biçimindedir.