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ı. API, masaüstü uygulamasını ve tarayıcı köprüsünü besleyen aynı yerel sunucuda yaşar.

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

Kimlik Doğrulama: Her ikisi de ayarlardaki API anahtarıyla korunan iki kimlik doğrulama yolu:

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

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

Yerel uygulama için (otomatik): Caiioo masaüstü uygulaması, tarayıcı uzantıları ve mobil uygulamalar, mevcut relay kimlik doğrulama başlığı (x-relay-auth; HTTP başlıkları büyük/küçük harfe duyarsızdır) aracılığıyla otomatik olarak kimlik doğrular. Manuel kuruluma gerek yoktur — uygulama bunu perde arkasında halleder. Relay-auth istekleri zaten güvenilir oldukları için Genel API'yi Etkinleştir anahtarını atlar; yalnızca bearer-token istekleri bu anahtarla korunur.

Kurulum:

Caiioo Ayarları > API Erişimi'ni açın
Genel API'yi Etkinleştir seçeneğini açın
Bir API erişim tokenı ayarlayın (seçtiğiniz herhangi bir dize — şifre gibi davranın)
Bu tokenı tüm API isteklerinde kullanın

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

Hız sınırları: Her /v1/* isteği istemci IP'si başına sınırlandırılmıştır — okumalar için dakikada 100 GET isteği ve birleşik olarak dakikada 30 yazma isteği (POST / PATCH / DELETE). Sınırı aşan istekler 429 alır. Webhook teslimatları (POST /v1/webhooks/:id) bearer kimlik doğrulamalı değildir ve bu sınırlara tabi değildir.

Profiller

Tek bir cihaz birden fazla kullanıcı profili barındırabilir (örneğin kişisel + iş). API, harici betiklerin mevcut profilleri incelemesine ve başka bir işlem yapmadan önce aktif olanı değiştirmesine olanak tanır. Profil oluşturma, güncelleme ve silme işlemleri kasıtlı olarak genel API üzerinden sunulmaz; bu akışlar uygulamanın ilk katılım (onboarding) arayüzüne aittir.

Profilleri listeleyin:

GET /v1/profiles

Silinmemiş her profil için bir giriş içeren { profiles: [...] } döner. Her giriş id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt bilgilerini içerir. Belirteç içeren alanlar (serviceCredentials, oauthConnections) ve senkronizasyon iç bileşenleri (vectorClock, lastModifiedBy) temizlenir. OAuth bağlantılarını incelemek için /v1/connectors kullanın.

Aktif profili alın:

GET /v1/profiles/active

Bu sunucu tarafından o anda kullanılan profil için { profile } döner. Bir profile kapsamlanmış tüm /v1/* kaynakları (iş parçacıkları, ekler, ayarlar, beceriler) bu profil üzerinde işlem yapar.

Aktif profili değiştirin:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "listeden-kullanici-uuid" }

Yeni aktif profil için { profile } döner. Kimlik bilinen bir profil değilse 404 döner.

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

Desteklenen tüm sağlayıcı türlerini döndürür. Mevcut olanlar: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. Her giriş; type, displayName, icon, requiresApiKey, hasApiKey bilgilerini ve aşağıdaki bayrakları içeren bir capabilities nesnesini kapsar.

Yetenek bayrağı	Anlamı
`supportsVision`	Sağlayıcı görüntü girişlerini kabul edebilir
`supportsPdfFile`	Sağlayıcı ham PDF dosyası içerik bloklarını yerel olarak kabul edebilir
`supportsToolCalling`	Sağlayıcı fonksiyon/araç çağırmayı destekler
`supportsStreaming`	Sağlayıcı token'ları kademeli olarak akış (stream) şeklinde iletir
`supportsExtendedThinking`	Sağlayıcı bir akıl yürütme/düşünme bütçesi sunar
`supportsPromptCaching`	Sağlayıcı prompt-cache direktiflerini destekler
`nativeReasoningBlocks`	Sağlayıcı düşünme sürecini yerel mesaj blokları olarak iletir (metin yerine)
`requiresThoughtSignature`	Sağlayıcı imzalı düşünme token'larının geri yansıtılmasını gerektirir

Yetenek bayrakları, her sağlayıcı sınıfının readonly capabilities alanını yansıtır (bkz. src/shared/providers/*-provider.ts) ve bir sapma nöbetçisi (drift sentinel) testi ile doğrulanır — matrisi sabit kodlamak yerine çalışma zamanında bu uç noktayı çağırın.

BYOK sağlayıcıları için notlar:

perplexity, küratörlüğünü yaptığı bir Sonar modelleri listesi sunar (Perplexity'nin herkese açık bir /models uç noktası yoktur).
cloudflare (AI Gateway) BYOK + çoklu satıcı yapısındadır; model listesi ağ geçidi yapılandırmanıza göre belirlenir ve /v1/providers/cloudflare/models tarafından boş bir dizi olarak döndürülür. Kendi ağ geçidi kataloğunuzu kullanın.

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

GET /v1/providers/openrouter/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. Sağlayıcının bir API anahtarı eksik olduğunda veya yukarı akış (upstream) kataloğuna ulaşılamadığında 503 hatası döndürür.

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.

Agent'ları Çalıştırma

Bu ana işlemdir — bir mesajı işlemek için bir agent çağırın.

İstek gövdesi — desteklenen alanlar

Alan	Gerekli	Açıklama
`agentId`	evet	Yerleşik mod ID'si (örneğin `general`) veya özel bir agent ID'si
`input.message`	evet	Kullanıcı mesaj metni
`input.attachments`	hayır	Bu tura eklenecek (daha önce `/v1/attachments` üzerinden yüklenmiş) ek ID'leri dizisi
`input.variables`	hayır	Agent'ın değişken çözücüsüne (variable resolver) dahil edilen çalışma bazlı değişken geçersiz kılmaları
`input.tabContext`	hayır	Sayfa bağlamı olarak enjekte edilen serbest biçimli dize (tarayıcı köprüsü tarafından kullanılır)
`input.messageId`	hayır	İstemci tarafından sağlanan mesaj ID'si — yeniden deneme durumunda mükerrer kayıtları önlemek (dedup) için kullanışlıdır
`threadId`	hayır	Devam edilecek mevcut thread. Belirtilmezse yeni bir thread oluşturulur ve döndürülür
`mode`	hayır	`"sync"` veya `"async"`. Varsayılan `"async"` değeridir

Senkron Mod (Synchronous Mode)

Tam yanıt için bekleyin:

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

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

Agent işlemi bitirdikten sonra { content, usage, status: "completed" } ile 200 döner. Agent hata verirse, { error, status: "error" } ile 500 döner. Senkron çalışmalar, terminal bir olay alınmazsa 5 dakika sonra status: "error" ile zaman aşımına uğrar — daha uzun sürebilecek işlemler için async + SSE kullanın.

Asenkron Mod (Asynchronous Mode)

Gönder 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öner.

Durum için sorgulama (Poll):

GET /v1/runs/{runId}

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

Olayları gerçek zamanlı izleme (SSE):

GET /v1/runs/{runId}/events

Her agent 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 agent (subagent) faaliyetleri ve terminal olayı (GENERATION_COMPLETE, GENERATION_ERROR veya GENERATION_CANCELLED).

Terminal olayından sonra, sunucu akışın sona erdiğini belirten açık bir işaretçi olarak event: terminal ve boş bir veri yükü içeren son bir SSE karesi yayınlar, ardından bağlantıyı kapatır. İstemciler, bu karenin alınmasını (veya bağlantının kapanmasını) okumayı durdurma sinyali olarak kabul etmelidir.

Çalışma zaten bittikten sonra abone olursanız, sunucu tam nihai record içeriğini barındıran RUN_SNAPSHOT tipinde bir kareyi yeniden oynatır, ardından event: terminal işaretçisini gönderir ve kapanır.

Bir çalışmayı iptal etme:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } } döner.

Threads

Threads (İş parçacıkları) konuşmalardır. 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

Mevcut profil için messages alanı çıkarılmış (ihtiyacınız olduğunda detay uç noktasını kullanın) { threads: [...] } döndürür. Diğer tüm alanlar korunur — id, title, createdAt, updatedAt, modeId, archived, kullanım istatistikleri, ayrıca ayarlanmışsa subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId. (Daha zengin veri yükü API'ye özeldir — WebSocket kenar çubuğu yayını, taşıma sınırlarının altında kalmak için daha dar bir veri seti kullanır.)

Tam mesaj içeriğiyle bir thread getir:

GET /v1/threads/{id}

messages dizisi dahil olmak üzere thread'in tamamını döndürür — her kullanıcı mesajı, asistan yanıtı, araç çağrısı ve araç sonucu.

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" }

{ thread } ile birlikte 201 döndürür. Yeni thread, kenar çubuğunda anında görünür (WebSocket yayını aracılığıyla). API, oluşturma sırasında uygulamanın aktif thread'ini asla değiştirmez — bunu istiyorsanız ayrıca PUT /v1/threads/active çağrısı yapın.

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 gerçek zamanlı olarak kenar çubuğuna yayınlanır.

Bir thread'i sil:

DELETE /v1/threads/{id}

Thread'i geçici olarak siler (senkronizasyon için işaret koyar). 204 döndürür. Silinen thread'ler çöp kutusuna taşınır ve çöp kutusu boşaltılana kadar 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ı — yani agent'lara harici araçlara ve veri kaynaklarına erişim sağlayan sunucuları — yönetin.

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 temizlenir.

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"
}

POST isteğinde kabul edilen isteğe bağlı alanlar: command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. Sunucu tarafından yönetilen alanlar (customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock, ...) API üzerinden ayarlanamaz.

Bir sunucuyu güncelle:

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

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

Güncellenebilir alanlar POST izin listesiyle aynıdır (credentialId ve oauthConnectionId dahil — bir OAuth bağlantısını silip yeniden oluşturmadan değiştirmek için kullanışlıdır). Sunucu tarafından yönetilen alanlar salt okunur kalır.

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 (SIGTERM, başarısız olursa SIGKILL).

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ç Kitleri (Tools & Toolkits)

Agent'ların kullandığı araçlara — web gezintisi, arama, takvim, Gmail, Slate ve daha fazlası — göz atın ve bunları çağırın.

Araç kitlerini listele (gruplandırılmış):

GET /v1/toolkits

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

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

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ı ile araç detaylarını al:

GET /v1/tools/calculator

{ tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } } döndürür.

Alan	Anlamı
`inputSchema`	Aracın girdisi için JSON Şeması — çağırmadan önce doğrulayın
`actions`	İsteğe bağlı alt eylemler (örneğin Slate `read`/`write`); her birinin `id`, `displayName`, `description` ve isteğe bağlı `requiredTier` alanı vardır
`requiredTier`	Minimum kullanıcı seviyesi (belirtilmemişse `free`). Kamu-API çağrısı `free` üzerindeki her şeyi reddeder
`requiredRuntimes`	Bu aracın kullanılabildiği platformlar (`macos`, `ios`, vb.); belirtilmemişse ⇒ her yer
`riskTier`	Onay riski: `low` (varsayılan), `medium`, `high`
`riskExplanation`	`riskTier` seviyesinin yükseltilmesinin insan tarafından okunabilir nedeni
`requiresApproval`	Araç her çağrıda kullanıcı onayı gerektirdiğinde `true` olur — kamu-API çağrısı bunları reddeder

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

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

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

{ 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. Araç thread kapsamlı bağlama ihtiyaç duyuyorsa (örneğin ek aramaları) isteğe bağlı bir threadId iletin.

Kısıtlamalar — kamu API'sinin reddettikleri:

Seviye kısıtlamalı araçlar (metadata.requiredTier !== 'free') → 403. Agent döngüsü, seviyeyi kullanıcının oturumuna göre kontrol eder; kamu API'sinin taşınan bir seviye bağlamı yoktur, bu nedenle muhafazakar politika reddetmektir. Bunun yerine doğru seviyeye sahip bir agent ile POST /v1/runs kullanın.
Onay gerektiren araçlar (metadata.approval.requiresApproval === true) → 403. Soru sorulacak bir insan döngüde yoktur. POST /v1/runs üzerinden çağırın (bu, istemi kullanıcıya gösterir) veya atlamak için uygulamada araç onay modunu approve_all olarak ayarlayın.
Uzak MCP araçları → /v1/runs kullanılması yönünde rehberlik ile birlikte 501 (agent alt süreç taşımasına ihtiyaç duyarlar).

Görüntü ve imaj kullanan araçlar: önce POST /v1/attachments üzerinden yükleyin, ardından döndürülen ek kimliğini (attachment ID) input içinde iletin (örneğin { "input": { "attachment_id": "att_abc", "prompt": "Bu resimde ne var?" } }). Araç, ikili dosyayı threadId aracılığıyla depolama alanından okur; baytları satır içinde (inline) iletmezsiniz.

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

Adları, kategorileri ve varsayılan kapsamlarıyla kayıtlı tüm OAuth sağlayıcılarını döndürür.

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

GET /v1/connectors

Mevcut profil için aktif bağlantıları döndürür. Tokenlar asla ifşa edilmez — yalnızca meta veriler (sağlayıcı, e-posta, durum, kapsamlar, zaman damgaları).

Tek bir bağlantıyı alın:

GET /v1/connectors/{id}

Bir bağlantı için meta verileri döndürür (sağlayıcı, e-posta, durum, kapsamlar, zaman damgaları). Tokenlar asla ifşa edilmez.

Bağlantı durumunu kontrol edin:

POST /v1/connectors/{id}/test

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

Bir bağlantıyı kaldırın:

DELETE /v1/connectors/{id}

Yeni bağlantılar oluşturmak, uygulama kullanıcı arayüzü veya /auth/* rotaları aracılığıyla etkileşimli OAuth akışını gerektirir.

Tetikleyiciler

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

Her tetikleyicinin bir kind (tür) ayrımı vardır: schedule (varsayılan — bir saate göre çalışır), webhook (harici bir servis webhook yoluna POST yaptığında çalışır) veya messaging (bağlı bir mesajlaşma adaptöründen çalışır — örneğin, bir kanal filtresiyle eşleşen gelen Slack/Discord mesajları).

Tetikleyicileri listeleyin:

GET /v1/triggers

{ triggers: [...] } döndürür. Her giriş, türünü, programını ve türe özgü alanları (örneğin, webhook tetikleyicileri için webhookSecret/webhookPath, mesajlaşma tetikleyicileri için messagingAdapterId/messagingChannelFilter) içerir.

Tek bir tetikleyiciyi alın:

GET /v1/triggers/{id}

Planlanmış bir tetikleyici oluşturun:

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

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

Desteklenen program 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\" } — yalnızca API aracılığıyla tetiklendiğinde

Bir tetikleyiciyi manuel olarak çalıştırın:

POST /v1/triggers/{id}/fire

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

Güncelleme veya silme:

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

Webhook'lar

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

Bir webhook tetikleyicisi oluşturun:

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

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

webhookSecret ve webhookPath ile birlikte 201 döner. Gizli anahtarı (secret) saklayın; veri paketlerini imzalamak için ona ihtiyacınız olacak.

Bir webhook gönderin:

# 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ı taşıyıcı yetkilendirme (bearer auth) gerektirmez; bunun yerine HMAC doğrulaması kullanır. Gönderilen çalışmanın threadId bilgisiyle birlikte 202 döner. Tetikleyici istemindeki {{webhook.body}} yer tutucusu, ham istek gövdesiyle değiştirilir.

Mesajlaşma tetikleyicileri

Mesajlaşma tetikleyicileri, bağlı bir mesajlaşma adaptörü (örneğin, Community Hub aracılığıyla yüklenen bir Slack veya Discord entegrasyonu) tetikleyicinin filtresiyle eşleşen bir gelen mesaj aldığında çalışır. kind: "messaging" ile oluşturun:

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

{
  "name": "Mention responder",
  "prompt": "Şuna yardımcı bir şekilde yanıt ver: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

Adaptör, eşleşen olayları tetikleyiciye göndermekten sorumludur; messagingChannelFilter adaptöre özgüdür.

Ö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}

Beceriler

Beceriler, ajanların referans alabileceği ve boş konuşma görünümünden hızlıca başlatabileceği kaydedilmiş istemlerdir. Hub üzerinden yüklenen beceriler (paket kurulumuyla yönetilenler) buraya dahil DEĞİLDİR; yalnızca kullanıcı tarafından yazılmış beceriler listelenir ve düzenlenebilir.

Becerileri listeleyin:

GET /v1/skills

Aktif profil için kullanıcı tarafından yazılmış becerilerin { skills: [...] } listesini döner. İşaretlenerek silinmiş, hub katmanlı ve senkronizasyon gölge becerileri filtrelenir.

Bir beceriyi alın:

GET /v1/skills/{id}

Bir beceri oluşturun:

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

{
  "prompt": "Sayfayı 3 maddede özetle.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Hızlı Özet",
  "description": "Aktif sayfanın üç maddelik özeti"
}

Yalnızca prompt gereklidir. modes (isteğe bağlı), beceriyi belirli ajan kimlikleriyle sınırlandırır; tüm modlar için boş bırakın. Sunucu tarafından atanan id, createdAt, updatedAt bilgilerini içeren yeni beceriyle birlikte 201 döner.

Bir beceriyi güncelleyin:

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

{ "prompt": "Güncellenmiş istem", "isFavorite": false }

Yamanabilir alanlar: prompt, tags, modes, displayName, description, isFavorite. Bir hub katmanlı beceriyi yamama girişimleri 404 döner.

Bir beceriyi silin:

DELETE /v1/skills/{id}

İşaretleyerek yumuşak silme yapar. 204 döner. Hub katmanlı beceriler 404 döner; bunun yerine kaynak paketi kaldırın.

İş 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 — ayrıntılar için `error` alanını kontrol edin
`401`	Yetkisiz — eksik veya geçersiz oturum gizli anahtarı
`403`	Yasak — örneğin, yerleşik bir ajanı değiştirmeye çalışmak
`404`	Bulunamadı
`409`	Çakışma — örneğin, ajan kimliği zaten mevcut
`422`	Doğrulama hatası — girdi araç şemasıyla eşleşmiyor
`429`	İstek sınırı aşıldı — Kimlik Doğrulama bölümündeki hız sınırı bütçelerine bakın
`500`	Sunucu hatası — `error` alanını kontrol edin
`501`	Uygulanmadı — özellik mevcut ancak bu şekilde kullanılamıyor
`503`	Servis 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.