REST API Referansı

Botonom platformunu kendi uygulamalarınıza ve kurumsal iş akışlarınıza entegre edin.

7 dk okuma3,500 görüntülenmeGüncelleme 2026-07-10

JuliaRehber Asistanı

Bu rehberde önce Kimlik Doğrulama (Authentication) ile başlıyor, sırasıyla Protokol ve Standartlar (Conventions) ve Temel API Endpoint'leri konularını ele alıp Yanıtı Metin Yerine Yapısal JSON (Schema) Olarak Alma ile tamamlıyoruz.

Kimlik Doğrulama (Authentication)

Tüm API istekleri bir kurumsal API anahtarı (bk_live_...) gerektirir. Anahtarınızı panelden oluşturabilirsiniz:

Panel → Geliştiriciler → Kimlik Bilgileri → Anahtar Oluştur

Anahtarın tam metni güvenlik gereği oluşturulurken yalnızca bir kez gösterilir. İsteklerinizde header olarak iletin:

curl "https://api.botonom.com/en/api/v1/agents/list/" \
  -H "X-Botonom-Api-Key: bk_live_your_key_here"

Alternatif olarak Authorization: Bearer bk_live_... başlığı da desteklenir. API anahtarı çalışma alanınıza özeldir; anahtarlarınızı panelden veya keys/list ve keys/revoke endpoint'leri üzerinden listeleyebilir ve dilediğiniz an iptal edebilirsiniz.

API anahtarınızı asla istemci (client-side) kodlarında açıkta bırakmayın. Tüm çağrıları güvenli backend sunucunuzdan yapın.

Protokol ve Standartlar (Conventions)

Base URL: https://api.botonom.com/en/api/v1

Endpoint yolları <resource>/<action>/ standardındadır; kimlik ve filtreler URL path'inde değil, query parameter olarak veya JSON body içinde iletilir.
agent_id parametresi daima agent'ın genel UUID değeridir (agents/list ile alınır).
Tüm API yanıtları standart bir envelope kullanır: {status, code, title, data, msg}. Başarısız durumlarda makine tarafından okunabilir error.code ve gerçek bir HTTP status code döner.
Idempotency-Key header'ı (maks 128 karakter) agents/command ve tüm kayıt oluşturma endpoint'lerinde desteklenir. Ağ kesintilerinde aynı isteği bu header ile tekrarlamak işlemi çoğaltmaz, önbelleğe alınan yanıtı döndürür; farklı bir payload ile aynı anahtar kullanılırsa 409 IDEMPOTENCY_CONFLICT döner.

API sözleşmemiz OpenAPI 3.0 olarak yayınlanmıştır; tüm endpoint'leri API Playground üzerinden canlı deneyebilirsiniz.

Temel API Endpoint'leri

Metot	Endpoint	Açıklama
GET	`agents/list`	Çalışma alanındaki agent'ları listeler (public id = UUID)
GET	`agents/get?agent_id=`	Belirli bir agent'ın detaylarını ve yeteneklerini getirir
POST	`agents/create`	Bir hazır şablondan yeni bir agent işe alır
POST	`agents/command`	Agent'a doğal dilde asenkron komut iletir
POST	`agents/command_reply`	Aynı sohbete bir sonraki mesajı gönderir (aynı çalışma)
GET	`agents/command_status?run_id=`	Komut çalıştırmasının durumunu ve sonucunu sorgular
GET / POST	`skills/list` · `skills/install`	Yetenek kataloğunu listeler, agent'a yetenek kurar veya kaldırır
POST	`contacts/create` · `calendar/event_create` · `tasks/create`	Agent'ın kullandığı ortak çalışma alanı kayıtlarını oluşturur
GET	`usage/tokens` · `billing/get`	Token tüketimi, kota ve faturalama bilgilerini getirir
POST	`webhooks/create`	İmzalı sistem event'lerine webhook aboneliği kaydeder

En kritik akış agents/command endpoint'idir: sisteminiz doğal dilde bir talimat gönderir, agent kendi karakteri, yetenekleri ve şirket izinleriyle bu görevi asenkron olarak yürütür.

POST /v1/agents/command
{
  "agent_id": "<agent-uuid>",
  "instruction": "ahmet@example.com adresine kısa bir hoş geldin e-postası gönder ve adıyla selamla.",
  "data": { "name": "Ahmet" },
  "autonomy": "full"
}

Yanıt (202 Accepted):

{
  "status": true,
  "code": 202,
  "data": {
    "run": { "run_id": "cmd_654741d0...", "status": "queued", "autonomy": "full" }
  },
  "msg": "Command queued"
}

Sonucu almak için agents/command_status?run_id=cmd_... endpoint'ini status değeri completed olana kadar sorgulayabilir (agent yanıtı result_text içinde gelir) veya agent.command.completed webhook event'ine abone olarak sonucu anlık alabilirsiniz.

Yanıtı Metin Yerine Yapısal JSON (Schema) Olarak Alma

result_text insanlar için doğal dilde yazılır. Eğer yanıtı kendi yazılımınız işleyecekse, istediğiniz veri yapısını schema parametresiyle belirtin; agent yanıtla birlikte alan adlarınızı içeren tip güvenli bir output JSON nesnesi döndürür:

POST /v1/agents/command
{
  "agent_id": "<agent-uuid>",
  "instruction": "Bu ayki siparişleri incele ve toplam ciroyu özetle.",
  "schema": {
    "type": "object",
    "properties": {
      "total_revenue": { "type": "number", "description": "Toplam ciro tutarı" },
      "currency":      { "type": "string", "enum": ["TRY", "USD"] },
      "top_product":   { "type": "string", "description": "En çok satan ürün adı" },
      "products": {
        "type": "array",
        "items": { "type": "object", "properties": { "name": { "type": "string" }, "revenue": { "type": "number" } } }
      }
    },
    "required": ["total_revenue", "top_product"]
  }
}

command_status her iki çıktıyı da döner:

{
  "run_id": "cmd_654741d0...",
  "status": "completed",
  "result_text": "Bu ayki toplam ciro 27.400 TL olarak gerçekleşti; en yüksek satışı Çalışma Masası yaptı...",
  "output": {
    "total_revenue": 27400,
    "currency": "TRY",
    "top_product": "Çalışma Masası",
    "products": [{ "name": "Çalışma Masası", "revenue": 10000 }]
  },
  "output_error": null
}