Bu belge, orijinal İngilizce metnin makine çevirisidir. Bu çeviri ile orijinal İngilizce sürüm arasında herhangi bir çelişki olması durumunda, İngilizce sürüm geçerli olacaktır. İngilizce orijinal metni oku

Genel API

Caiioo, her şeyi programlı olarak kontrol etmenizi sağlayan bir REST API içerir: aracıları çalıştırın, araçları yönetin, görevleri planlayın ve daha fazlasını yapın. API, masaüstü uygulamasını ve tarayıcı köprüsünü besleyen aynı yerel sunucuda barındırılır.

Temel URL: http://localhost:3847/v1

Kimlik Doğrulama: Her ikisi de ayarlardaki API anahtarı ile denetlenen iki kimlik doğrulama yolu vardır:

Harici tüketiciler için (betikler, entegrasyonlar, curl): Ayarlar > API Erişimi bölümünde bir API erişim jetonu belirleyin, ardından bunu bir Bearer jetonu olarak kullanın:

curl -H "Authorization: Bearer API_JETONUNUZ" http://localhost:3847/v1/providers

Yerel uygulama için (otomatik): Caiioo masaüstü uygulaması, tarayıcı uzantıları ve mobil uygulamalar mevcut relay yetkilendirme başlığı (X-Relay-Auth) aracılığıyla otomatik olarak kimlik doğrular. Manuel kuruluma gerek yoktur — uygulama bunu arka planda halleder.

Kurulum:

  1. Caiioo Ayarları > API Erişimi'ni açın
  2. Genel API'yi Etkinleştir seçeneğini açın
  3. Bir API erişim jetonu belirleyin (seçeceğiniz herhangi bir dize — buna bir şifre gibi davranın)
  4. Bu jetonu tüm API isteklerinde kullanın

API, localhost üzerinden ve özel relay aracılığıyla kullanılabilir. Mevcut durum ve kurulum talimatları için GET /v1/auth/info (kimlik doğrulama gerektirmez) adresini kontrol edin.

Sağlayıcılar ve Modeller

Hangi LLM sağlayıcılarının yapılandırıldığını ve hangi modellerin mevcut olduğunu keşfedin.

Sağlayıcıları listele:

GET /v1/providers

Yapılandırılmış tüm sağlayıcı türlerini (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten ve eklenen diğerleri) yetenek bayraklarıyla (supportsVision, supportsToolCalling, supportsStreaming, vb.) ve bir API anahtarının yapılandırılıp yapılandırılmadığı bilgisiyle birlikte döndürür.

Bir sağlayıcı için modelleri listele:

GET /v1/providers/anthropic/models

O sağlayıcı için model kataloğunu döndürür. Her model, mevcut olduğunda id, displayName ve contextLength bilgilerini içerir.

Tüm sağlayıcılar genelinde düz katalog:

GET /v1/models

Yapılandırılmış her sağlayıcıdaki modelleri tek bir listede birleştirir. API anahtarı olmayan sağlayıcılar atlanır ve warnings kısmında listelenir.

Aracılar

Aracılar Caiioo'nun çekirdeğidir. Her aracı bir Mod'dur — kendi sistem istemi, araçları, değişkenleri ve yetenekleri olan yapılandırılmış bir kişilik.

Tüm aracıları listele:

GET /v1/agents

Yerleşik aracıları (Alışveriş, İş Yeri, Genel) ve oluşturduğunuz tüm özel aracıları döndürür. Her biri source: \"builtin\" veya source: \"custom\" olarak etiketlenir.

Özel bir aracı oluştur:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"arastirma-aracim\",
  \"branding\": {
    \"name\": \"Araştırma Aracısı\",
    \"description\": \"Web'de arama yapar ve bulguları özetler\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Sen bir araştırma asistanısın. Her zaman kaynak belirt.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Oluşturulan aracı ile 201 döndürür. Senkronizasyon için otomatik olarak bir vektör saati eklenir.

Bir aracıyı güncelle:

PATCH /v1/agents/arastirma-aracim
Content-Type: application/json

{ \"branding\": { \"name\": \"Araştırma Aracısı\", \"description\": \"Güncellenmiş açıklama\" } }

Yamayı mevcut aracıyla birleştirir ve vektör saatini artırır. Yerleşik aracılar 403 döndürür — salt okunurdur.

Bir aracıyı sil:

DELETE /v1/agents/arastirma-aracim

Tombstone aracılığıyla yazılımsal silme yapar (cihazlar arasında senkronize edilir). 204 döndürür.

Aracıları Çalıştırma

Ana olay burası — bir mesajı işlemek için bir aracıyı çağırın.

Senkron Mod

Tam yanıtı bekleyin:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "Bugün Paris'te hava nasıl?" },
  "mode": "sync"
}

Aracı işlemi bitirdikten sonra { content, usage, status: "completed" } ile 200 döndürür. Aracı hata verirse, { error, status: "error" } ile 500 döndürür.

Asenkron Mod

Yolla ve unut — uzun süren görevler için kullanışlıdır:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Yenilenebilir enerji trendleri hakkında 2000 kelimelik bir analiz yaz" },
  "mode": "async"
}

Hemen { runId, threadId, status: "running" } ile 202 döndürür.

Durum için sorgulama:

GET /v1/runs/{runId}

{ run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } } döndürür. Durum; running, completed, error veya cancelled değerlerinden biridir.

Olayları gerçek zamanlı akışla izle (SSE):

GET /v1/runs/{runId}/events

Her aracı olayını gerçekleştiği anda bir text/event-stream olarak döndürür: GENERATION_STARTED, STREAMING_CONTENT, araç çağrıları, alt aracı etkinlikleri ve terminal olayı (GENERATION_COMPLETE, GENERATION_ERROR veya GENERATION_CANCELLED). Akış, terminal olayından sonra sona erer.

Bir çalışmayı iptal et:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } } döndürür.

Threads

Threads (Konuşma Dizileri) görüşmelerdir. Her agent çalışması bir thread içinde gerçekleşir ve thread'ler oturumlar arasında kalıcıdır. API; thread'leri programlı olarak listelemenize, okumanıza, oluşturmanıza ve yönetmenize olanak tanır.

Tüm thread'leri listele (yalnızca meta veriler):

GET /v1/threads

Performans için mesajların çıkarıldığı, mevcut profile ait thread'leri döndürür. Her thread; id, title, createdAt, updatedAt, modeId, archived ve kullanım istatistiklerini içerir.

Tam mesaj içeriğiyle bir thread getir:

GET /v1/threads/{id}

messages dizisi dahil olmak üzere tüm thread'i döndürür — her kullanıcı mesajı, assistant yanıtı, tool call ve tool result içeriğe dahildir.

Sadece mesajları getir:

GET /v1/threads/{id}/messages

Yalnızca messages dizisini döndürür — sadece konuşmaya ihtiyacınız olduğunda tam thread nesnesinden daha hafiftir.

Bir thread oluştur:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

Yeni thread ile birlikte 201 döndürür. Varsayılan olarak API, uygulamanın aktif thread'ini DEĞİŞTİRMEZ — bunu istiyorsanız gövdede "setActive": true değerini gönderin. Yeni thread, yan menüde anında görünür (WebSocket yayını aracılığıyla).

Bir thread'i güncelle:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

Güncellenebilir alanlar: title, modeId, archived, lastUsedModel. Değişiklikler yan menüye gerçek zamanlı olarak yansıtılır.

Bir thread'i sil:

DELETE /v1/threads/{id}

Thread'i geçici olarak siler (senkronizasyon için tombstone). 204 döndürür. Silinen thread'ler çöp kutusuna taşınır ve çöp kutusu boşaltılana kadar geri kurtarılabilir.

Aktif thread:

GET /v1/threads/active            # { threadId } döndürür
PUT /v1/threads/active            # Gövde: { "threadId": "..." }

Çöp kutusu yönetimi:

GET /v1/threads/trash/count       # { count } döndürür
POST /v1/threads/trash/empty      # { deletedCount, protectedCount } döndürür

Korumalı thread'ler (veri tutma ayarı aracılığıyla saklananlar), çöp kutusu boşaltma işlemine dahil edilmez.

API aracılığıyla bir konuşmaya devam etme: Mevcut bir thread'e takip mesajı göndermek için thread ID'si ile POST /v1/runs kullanın:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Agent, thread'deki tüm konuşma geçmişini görür.

Ekler

Ekler; dizilere bağlı dosyalardır (ekran görüntüleri, PDF'ler, belgeler, yüklenen resimler, oluşturulan yapay nesneler). API bunları listelemenize, yüklemenize, indirmenize ve yönetmenize olanak tanır.

Tüm ekleri listele (sadece meta veriler):

GET /v1/attachments

Mevcut profil için ek meta verilerini döndürür. Ağır alanlar (dataUrl, extractedContent, extractedImages) temizlenir; bunlar için detay veya içerik uç noktalarını kullanın.

Belirli bir dizi için ekleri listele:

GET /v1/threads/{threadId}/attachments

Ek meta verilerini al:

GET /v1/attachments/{id}

extractedContent (OCR metni, ayrıştırılmış markdown), contentType, fileName, size ve bir hasContent bayrağı dahil olmak üzere tam meta verileri döndürür. Ham ikili dosya dahil DEĞİLDİR; bunun için /content uç noktasını kullanın.

Ek ikili dosyasını indir:

GET /v1/attachments/{id}/content

Doğru Content-Type ve Content-Disposition başlıklarıyla ham dosyayı döndürür. Bunu bir dosyaya yönlendirin:

curl -o cikti.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Bir ek yükle:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "rapor.pdf",
  "description": "Çeyrek raporu",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl base64 kodlu bir veri URL'sidir. Yeni ek kimliği ile 201 döndürür. Ek, belirtilen diziye bağlanır.

Ek meta verilerini güncelle:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Güncellenmiş açıklama", "fileName": "yeni-isim.pdf" }

Bir eki sil:

DELETE /v1/attachments/{id}

Tombstone aracılığıyla yazılımsal silme yapar. 204 döndürür.

MCP Sunucuları

MCP (Model Context Protocol) sunucu bağlantılarınızı yönetin — bu sunucular, agent'lara harici araçlara ve veri kaynaklarına erişim sağlar.

Yapılandırılmış sunucuları listele:

GET /v1/mcp-servers

Mevcut profil için tüm MCP sunucu yapılandırmalarını döndürür. Hassas alanlar (authToken, env, credentialId) yanıttan çıkarılır.

Bir sunucunun yapılandırmasını al:

GET /v1/mcp-servers/{id}

Yeni bir MCP sunucusu ekle:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

Uzak HTTP sunucuları için "command" yerine "url" kullanın:

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Bir sunucuyu güncelle:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

Bir sunucuyu etkinleştir/devre dışı bırak:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

Bir sunucuyu sil:

DELETE /v1/mcp-servers/{id}

Süreç Yönetimi

Yerel (stdio) MCP sunucuları için sunucu sürecini doğrudan yönetebilirsiniz.

Çalışan süreçleri listele:

GET /v1/mcp-servers/processes

pid, startedAt ve running durumu ile çalışan sunucu süreçlerini döndürür.

Bir sunucuyu başlat:

POST /v1/mcp-servers/{id}/start

Sunucu yapılandırmasından command/args/env bilgilerini okur ve süreci başlatır. Süreç durumunu döndürür.

Bir sunucuyu durdur:

POST /v1/mcp-servers/{id}/stop

Sunucu sürecini güvenli bir şekilde kapatır (SIGKILL yedeği ile SIGTERM).

Doğrudan bir JSON-RPC metodu çağır:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

Sunucuya ham bir JSON-RPC 2.0 isteği gönderir ve sonucu döndürür. Hata ayıklama veya araçlar API'si aracılığıyla sunulmayan metodları çağırmak için kullanışlıdır.

Araçlar ve Araç Setleri

Aracıların kullandığı araçlara göz atın ve onları çağırın: web gezintisi, arama, takvim, Gmail, Slate ve daha fazlası.

Araç setlerini listele (gruplanmış):

GET /v1/toolkits

Kategoriye göre gruplandırılmış yerleşik araçları (Üretkenlik, Arama, Yardımcı Programlar vb.) ve bağlı tüm MCP sunucularını, her biri kendi eylemleri listelenmiş ayrı araç setleri olarak döndürür.

Tüm araçları listele (düz):

GET /v1/tools
GET /v1/tools?source=embedded   # Sadece yerleşik araçlar
GET /v1/tools?source=mcp        # Sadece MCP sunucu araçları

Girdi şemasıyla araç detaylarını al:

GET /v1/tools/calculator

Aracın girdi parametreleri için JSON Şemasını döndürür, böylece çağırmadan önce doğrulama yapabilirsiniz.

Bir aracı doğrudan çağır:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" } }

{ result } döndürür. Girdi, aracın şemasına göre doğrulanır; geçersiz girdi detaylarla birlikte 422 döndürür. Uzak MCP araçları, /v1/runs kullanılması yönünde rehberlik ederek 501 döndürür (aracı alt süreç taşımasına ihtiyaç duyarlar).

Bağlayıcılar

OAuth entegrasyonlarını yönetin: Google, Microsoft, GitHub, Notion, Slack ve daha fazlası.

Mevcut entegrasyonlara göz atın:

GET /v1/connectors/catalog

Kayıtlı tüm OAuth sağlayıcılarını adları, kategorileri ve varsayılan kapsamları ile döndürür.

Bağlı hesaplarınızı listele:

GET /v1/connectors

Mevcut profil için aktif bağlantıları döndürür. Belirteçler asla ifşa edilmez; sadece meta veriler (sağlayıcı, e-posta, durum, kapsamlar, zaman damgaları) paylaşılır.

Bağlantı durumunu kontrol et:

POST /v1/connectors/{id}/test

{ health: { status, isTokenExpired, canRefresh } } döndürür.

Bir bağlantıyı kaldır:

DELETE /v1/connectors/{id}

Yeni bağlantılar oluşturmak, uygulama arayüzü veya /auth/* yolları üzerinden etkileşimli OAuth akışını gerektirir.

Tetikleyiciler

Aracıları otomatik olarak çalışacak şekilde planlayın: günlük özetler, haftalık raporlar, aralık tabanlı izleme.

Tetikleyicileri listele:

GET /v1/triggers

Planlanmış bir tetikleyici oluştur:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Sabah Özeti",
  "prompt": "Okunmamış e-postalarımı ve bugünkü takvimimi özetle",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Desteklenen plan türleri:

  • { "type": "interval", "minutes": 60 } — her N dakikada bir (min 15, maks 1440)
  • { "type": "daily", "time": "09:00" } — her gün belirli bir saatte
  • { "type": "weekly", "day": "mon", "time": "09:00" } — haftalık
  • { "type": "weekdays", "time": "08:30" } — Pazartesi'den Cuma'ya
  • { "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — belirli günler
  • { "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — aylık
  • { "type": "manual" } — sadece API üzerinden ateşlendiğinde

Bir tetikleyiciyi manuel olarak ateşle:

POST /v1/triggers/{id}/fire

Sonuçlanan çalışma için bir threadId ile 202 döndürür.

Güncelle veya sil:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Webhook'lar

Webhook tetikleyicileri, harici servislerin (CI/CD, izleme, form oluşturucular) HTTP üzerinden bir aracı çalışmasını tetiklemesine olanak tanır.

Bir webhook tetikleyicisi oluştur:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Dağıtım kancası",
  "prompt": "Bir dağıtım gerçekleşti: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

Bir webhookSecret ve webhookPath ile 201 döndürür. Gizli anahtarı saklayın; veri yüklerini imzalamak için ona ihtiyacınız olacak.

Bir webhook gönder:

# Ham istek gövdesinin HMAC-SHA256'sını hesaplayın
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

Webhook uç noktası bearer yetkilendirmesi gerektirmez; bunun yerine HMAC doğrulaması kullanır. Gönderilen çalışmanın threadId bilgisi ile 202 döndürür. Tetikleyici istemindeki {{webhook.body}} yer tutucusu, ham istek gövdesi ile değiştirilir.

Özel Fonksiyonlar

Aracıların çağırabileceği kendi araçlarınızı oluşturun. Fonksiyonlar JavaScript veya Python dilinde yazılır ve bir sandbox içinde yürütülür.

Fonksiyonları listele:

GET /v1/functions

Bir fonksiyon oluştur:

POST /v1/functions
Content-Type: application/json

{
  "name": "vki_hesapla",
  "description": "Boy ve kilodan Vücut Kitle İndeksini hesapla",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

JavaScript fonksiyonları input alır ve bir sonuç döndürmelidir. Python fonksiyonları bir result değişkeni atar:

# Python örneği
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Bir fonksiyonu doğrudan yürüt:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Güvenlik: JavaScript, Node'un vm sandbox'ında çalışır (dosya sistemi veya ağ erişimi yok, 10 saniye zaman aşımı). Python, 30 saniye zaman aşımı ile bir alt süreç olarak çalışır. Her ikisi de yürütmeden önce girdiyi doğrular.

Güncelle veya sil:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

İş Akışları

Birden fazla ajanı bir DAG (yönlendirilmiş döngüsüz grafik) içinde yönetin; adımları mümkün olduğunda paralel olarak çalıştırın ve önceki adımlardan gelen çıktıları sonraki adımlara aktarın.

Bir iş akışı grafiğini doğrulayın:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Yenilenebilir enerji trendlerini araştır" },
      { "id": "analyze", "agentId": "general", "prompt": "Rakip fiyatlandırmasını araştır" },
      { "id": "report", "agentId": "general", "prompt": "Şunları birleştiren bir rapor yaz: {{outputs.research}} ve {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

{ valid: true/false, errors: [...] } döndürür. Döngüleri, yinelenen kimlikleri ve eksik bağımlılık referanslarını kontrol eder.

Bir iş akışını yürütün:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Yenilenebilir enerji trendlerini araştır" },
      { "id": "summarize", "agentId": "general", "prompt": "Özetle: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

{ status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} } döndürür.

Bağımsız düğümler (ortak bağımlılığı olmayanlar) paralel olarak çalışır. Bir düğümün istemindeki {{outputs.nodeId}} yer tutucusu, belirtilen üst akış düğümünün içerik çıktısıyla değiştirilir. Her düğüm tam bir ajan çalışmasıdır, bu nedenle araçları kullanabilir, web'de gezinebilir ve hedef ajanın tüm yeteneklerine erişebilir.

Bilgi Tabanları

Belgeleri, aracıların referans alabileceği aranabilir koleksiyonlar halinde düzenleyin.

Bilgi tabanlarını listele:

GET /v1/knowledge/bases

Bir bilgi tabanı oluştur:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Araştırma Makaleleri" }

Yeni taban kimliği ile 201 döndürür.

Bir bilgi tabanına belge yükle:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "arastirma-makalesi.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Yenilenebilir enerji trendleri 2026"
}

dataUrl alanı base64 kodlu bir veri URL'sidir. Belge meta verileri ile 201 döndürür.

Bir bilgi tabanındaki belgeleri listele:

GET /v1/knowledge/bases/{id}/documents

Bir bilgi tabanı içinde arama yap:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "yenilenebilir enerji" }

Dosya adı ve açıklamaya göre eşleşen belgeleri döndürür. Semantik (vektör) arama gelecek bir sürümde eklenecektir.

Bir belgeyi veya bilgi tabanını sil:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Aracıları Dışa Aktar ve İçe Aktar

Aracıları cihazlar, ekipler veya Topluluk Merkezi arasında taşınabilir paketler olarak paylaşın.

Bir aracıyı dışa aktar:

POST /v1/agents/{id}/export

Aracı tanımını, araç gereksinimlerini (etkinleştirilmiş araçlardan türetilen), bağlayıcı gereksinimlerini (hangi OAuth sağlayıcılarının gerekli olduğu) ve tetikleyici şablonlarını içeren bir JSON paketi döndürür. Senkronizasyon meta verileri temizlenir — paket temiz, bağımsız bir taslaktır.

Bir aracıyı içe aktar:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"paylasilan-arastirma-aracisi\",
      \"branding\": { \"name\": \"Araştırma Aracısı\", \"description\": \"Ekipten\" },
      \"defaultSettings\": { \"systemPrompt\": \"Şeyleri araştırırsın.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Yüklenen aracı ile 201 döndürür. Yerleşik veya mevcut aracılarla ID çakışmaları 409 döndürür.

Hata Yönetimi

API standart HTTP durum kodlarını kullanır:

Kod Anlamı
200 Başarılı
201 Oluşturuldu
202 Kabul Edildi (asenkron işlem başladı)
204 Silindi (içerik yok)
400 Hatalı istek — detaylar için error alanını kontrol edin
401 Yetkisiz — eksik veya geçersiz oturum gizli anahtarı
403 Yasak — örn. yerleşik bir aracıyı değiştirmeye çalışmak
404 Bulunamadı
409 Çakışma — örn. aracı kimliği zaten mevcut
422 Doğrulama hatası — girdi araç şemasıyla eşleşmiyor
500 Sunucu hatası — error alanını kontrol edin
501 Uygulanmadı — özellik mevcut ancak bu yolla kullanılamıyor
503 Hizmet kullanılamıyor — depolama veya sağlayıcı hazır değil

Tüm hata yanıtları { "error": "insan tarafından okunabilir mesaj" } içerir.

Hızlı Başlangıç Örneği

İşte tam bir iş akışı: bir aracı oluşturun, çalıştırın ve sonuçları akışla alın.

# 1. Özel bir aracı oluşturun
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hizli-ozetleyici",
    "branding": { "name": "Hızlı Özetleyici" },
    "defaultSettings": {
      "systemPrompt": "Herhangi bir girdiyi 3 madde işaretiyle kısa ve öz bir şekilde özetle.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Asenkron olarak çalıştırın
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "hizli-ozetleyici", "input": { "message": "Şunu özetle: https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. Olayları akışla alın
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Paylaşmak için aracıyı dışa aktarın
curl -X POST http://localhost:3847/v1/agents/hizli-ozetleyici/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.