API Genel Bakış & Temel URL

beginner 🤖 LLM uyumlu 3 dk · 551 kelime Güncellendi: 2026-06-27 Türkçe

Tüm Synapse API uç noktaları, temel URL, kimlik doğrulama desenleri ve yanıt biçimleri bir bakışta.

Bu makaleyi şu şekilde oku: 📄 Düz metin ⚡ JSON 🤖 LLM biçimi

API Genel Bakış & Temel URL

Synapse API, RESTful bir HTTP API'sidir. Tüm uç noktalar JSON döndürür (belirtilenler hariç). Bu sayfa, belirli uç noktalara dalmadan önce bilmeniz gereken temel bilgileri kapsar.

Temel URL

https://synapse.schaefer.zone

Bu dokümantasyondaki tüm yollar bu temel URL'ye göredir. Self-hosted örnekler için kendi URL'nizle değiştirin.

Kimlik Doğrulama

İki yöntem, ikisi de Authorization başlığı üzerinden gönderilir:

Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints

Veya sorgu parametresi üzerinden (60/dakika hız sınırıyla):

?key=YOUR_MIND_KEY

Detaylar için bkz. Kimlik Doğrulama.

Uç Nokta Grupları

Grup	Kimlik Doğrulama	Açıklama
Public	Yok	Açılış sayfası, sağlık, OpenAPI, docs
Memory	Mind Key	CRUD, arama, senkronizasyon, gömmeler
Chat	Mind Key / JWT	İnsan ve ajan arasında asenkron mesajlaşma
Tasks	Mind Key	Görev yönetimi
Scripts	Mind Key / JWT	Kalıcı betik deposu
Scheduler	Mind Key	Cron işleri + değişkenler
Webhooks	Mind Key	Olaylarda HTTP geri aramaları
Computers	Mind Key / JWT	Uzak bilgisayar kontrolü
User/Minds	JWT	Hesap + mind yönetimi
Sharing	JWT	Kullanıcılar arası mind paylaşımı
Push	JWT	Web Push abonelikleri
Tools	Yok	Saat, hesap, rastgele (herkese açık yardımcılar)

Yanıt Biçimleri

JSON (varsayılan): { "key": "value", ... }
Düz metin: /memory/recall, LLM için optimize edilmiş metin döndürür
HTML: /, /docs, /human, /support, /playground

Standart Yanıt Zarfı

Başarılı yanıtlar veriyi doğrudan döndürür:

{ "id": "mem_001", "status": "stored" }

Hata yanıtları şu biçimi kullanır:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}

`docs` alanı, yaygın hatalar için ilgili dokümantasyona bağlantı verir.

HTTP Durum Kodları

Kod	Anlamı
200	Başarılı (GET, PUT)
201	Oluşturuldu (POST)
204	İçerik yok (DELETE)
400	Hatalı istek (doğrulama hatası)
401	Yetkisiz (eksik/geçersiz token)
403	Yasak (yanlış token tipi)
404	Bulunamadı (yol mevcut değil)
409	Çakışma (yinelenen)
429	Çok fazla istek (hız sınırı)
500	Sunucu hatası

Keşfedilebilirlik Uç Noktaları

Uç Nokta	Amaç
`GET /`	Açılış sayfası (LLM için optimize edilmiş)
`GET /endpoints`	Tüm uç noktaların makine tarafından okunabilir listesi
`GET /endpoints?format=text`	Düz metin uç nokta listesi
`GET /openapi.json`	OpenAPI 3.0 belirtimi
`GET /help`	Tam API dokümantasyonu (HTML)
`GET /help?format=json`	JSON olarak API docs
`GET /docs`	Dokümantasyon sistemi (HTML)
`GET /docs?format=json`	Dokümantasyon dizini (JSON)
`GET /docs?format=text&scope=all`	Tüm docs tek metin bloğu olarak
`GET /playground`	Etkileşimli API playground

Hız Sınırları

Kimlik Doğrulama Yöntemi	Sınır
Mind Key (header)	Yok
Mind Key (?key=)	IP başına 60/dakika
JWT (header)	Yok
Herkese açık uç noktalar	Yok

Hız sınırına takılan yanıtlar şunları içerir:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)

Sayfalama

Liste uç noktaları ?limit= ve ?offset= destekler:

GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending

Varsayılan sınır: 100. Maksimum sınır: 500.

CORS

Tüm uç noktalar tarayıcı tabanlı istemciler için CORS'u destekler:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile

SDK'lar & İstemciler

Node.js SDK: npm install synapse-memory-sdk (repo)
MCP Server: npx -y synapse-mcp-api@latest (repo)
HTTP istemcisi: herhangi bir HTTP kütüphanesi (curl, fetch, axios vb.)

Sonraki Adımlar

Memory API — en önemli uç noktalar
Chat API — asenkron insan-ajan iletişimi
Hatalar & Hata Yönetimi