API SSS

Synapse API hakkında yaygın sorular.

Nasıl kimlik doğrularım?

İki yöntem:

1. Mind Key (veri uç noktaları için): Authorization: Bearer mk_...
2. JWT (hesap uç noktaları için): Authorization: Bearer eyJ...

Veya sorgu parametresi ile (60 istek/dakika sınırı): ?key=mk_...

Bkz. Kimlik Doğrulama.

Mind Key ve JWT arasındaki fark nedir?

• Mind Key: kiracı kapsamlı, asla sona ermez, memory/chat/tasks verileri için
• JWT: kullanıcı kapsamlı, 7 günlük son kullanma, hesap/mind yönetimi için

Bkz. Mind Key ve JWT.

Neden 401 Unauthorized alıyorum?

Yaygın nedenler:

1. Authorization başlığı eksik
2. Geçersiz Mind Key (mk_ ile başladığını doğrulayın)
3. Mind Key gerekendiye JWT kullanma (veya tersi)
4. Mind Key iptal edilmiş

Çözüm: Token'ınızı doğrulayın. Bkz. Kimlik Doğrulama.

Neden 404 Not Found alıyorum?

Yanlış bir uç nokta yolu kullandınız. Synapse'te yalnızca GET /endpoints içinde listelenen yollar mevcuttur.

Çözüm: Tüm geçerli yolları görmek için GET /endpoints çağırın. Tahmin etmeyin.

Neden 429 Too Many Requests alıyorum?

?key= sorgu parametresi kimlik doğrulaması kullanıyorsunuz, bu da 60/dakika ile sınırlıdır.

Çözüm: Authorization: Bearer başlığına geçin (hız sınırı yok).

Bkz. Hız Sınırları.

Tüm uç noktaları nasıl listelerim?

curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text

Doğru uç noktayı nasıl bulurum?

1. Makine tarafından okunabilir liste için GET /endpoints kontrol edin
2. Tam API docs için GET /help kontrol edin
3. Dokümantasyon sistemi için GET /docs göz atın
4. OpenAPI 3.0 spec için GET /openapi.json kullanın

POST yerine GET kullanabilir miyim?

Bazı POST uç noktalarının yalnızca URL kullanan araçlar için GET karşılığı vardır:

• POST /memory ↔ GET /memory/store?content=...
• POST /mind/task ↔ GET /mind/task?title=...
• POST /chat/reply ↔ GET /chat/reply?content=...

Mevcut GET varyantları için GET /endpoints kontrol edin.

Hataları nasıl ele alırım?

Tüm hatalar JSON döndürür:

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

Bkz. Hatalar & Hata Yönetimi.

İstek gövdesi sınırı nedir?

10 MB. Daha büyük yükler için (örn. dosya yüklemeleri) multipart uç noktalarını kullanın.

API CORS destekliyor mu?

Evet. Tüm uç noktalar şunu döndürür:

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

Bir SDK var mı?

Evet:

• Node.js: npm install synapse-memory-sdk
• MCP: npx -y synapse-mcp-api@latest

Detaylar için bkz. API Genel Bakış.

Nasıl sayfalandırırım?

?limit= ve ?offset= kullanın:

curl ".../memory?limit=50&offset=100"

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

Bellekleri kategoriye veya etikete göre filtreleyebilir miyim?

Evet:

curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"

Bellekleri nasıl ararım?

İki yol:

1. FTS5 anahtar kelime arama: GET /memory/search?q=docker+swarm
2. Anlamsal arama: GET /memory/semantic-search?q=container+orchestration

Bkz. FTS5 Arama ve Anlamsal Arama.

Bir belleği nasıl güncellerim?

Aynı category + key ile POST /memory — mevcut bellek güncellenir, çoğaltılmaz.

# Initial store
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Update (same key)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Bir belleği nasıl silerim?

curl -X DELETE -H "Authorization: Bearer $KEY" \
     https://synapse.schaefer.zone/memory/mem_001

Toplu silebilir miyim?

Evet:

curl -X POST .../memory/bulk-delete \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

Sonraki Adımlar

• API Genel Bakış
• Hatalar & Hata Yönetimi
• Kimlik Doğrulama