{"title":"API Genel Bakış & Temel URL","slug":"overview","category":"api","summary":"Tüm Synapse API uç noktaları, temel URL, kimlik doğrulama desenleri ve yanıt biçimleri bir bakışta.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":551,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# API Genel Bakış & Temel URL\n\nSynapse 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.\n\n## Temel URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nBu dokümantasyondaki tüm yollar bu temel URL'ye göredir. Self-hosted örnekler için kendi URL'nizle değiştirin.\n\n## Kimlik Doğrulama\n\nİki yöntem, ikisi de `Authorization` başlığı üzerinden gönderilir:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # for data endpoints\nAuthorization: Bearer YOUR_JWT # for account endpoints\n```\n\nVeya sorgu parametresi üzerinden (60/dakika hız sınırıyla):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nDetaylar için bkz. [Kimlik Doğrulama](/docs/getting-started/authentication).\n\n## Uç Nokta Grupları\n\n| Grup | Kimlik Doğrulama | Açıklama |\n|-------|------|-------------|\n| Public | Yok | Açılış sayfası, sağlık, OpenAPI, docs |\n| Memory | Mind Key | CRUD, arama, senkronizasyon, gömmeler |\n| Chat | Mind Key / JWT | İnsan ve ajan arasında asenkron mesajlaşma |\n| Tasks | Mind Key | Görev yönetimi |\n| Scripts | Mind Key / JWT | Kalıcı betik deposu |\n| Scheduler | Mind Key | Cron işleri + değişkenler |\n| Webhooks | Mind Key | Olaylarda HTTP geri aramaları |\n| Computers | Mind Key / JWT | Uzak bilgisayar kontrolü |\n| User/Minds | JWT | Hesap + mind yönetimi |\n| Sharing | JWT | Kullanıcılar arası mind paylaşımı |\n| Push | JWT | Web Push abonelikleri |\n| Tools | Yok | Saat, hesap, rastgele (herkese açık yardımcılar) |\n\n## Yanıt Biçimleri\n\n- **JSON** (varsayılan): `{ \"key\": \"value\", ... }`\n- **Düz metin**: `/memory/recall`, LLM için optimize edilmiş metin döndürür\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Standart Yanıt Zarfı\n\nBaşarılı yanıtlar veriyi doğrudan döndürür:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nHata yanıtları şu biçimi kullanır:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n> [!NOTE]\n> `docs` alanı, yaygın hatalar için ilgili dokümantasyona bağlantı verir.\n\n## HTTP Durum Kodları\n\n| Kod | Anlamı |\n|------|---------|\n| 200 | Başarılı (GET, PUT) |\n| 201 | Oluşturuldu (POST) |\n| 204 | İçerik yok (DELETE) |\n| 400 | Hatalı istek (doğrulama hatası) |\n| 401 | Yetkisiz (eksik/geçersiz token) |\n| 403 | Yasak (yanlış token tipi) |\n| 404 | Bulunamadı (yol mevcut değil) |\n| 409 | Çakışma (yinelenen) |\n| 429 | Çok fazla istek (hız sınırı) |\n| 500 | Sunucu hatası |\n\n## Keşfedilebilirlik Uç Noktaları\n\n| Uç Nokta | Amaç |\n|----------|---------|\n| `GET /` | Açılış sayfası (LLM için optimize edilmiş) |\n| `GET /endpoints` | Tüm uç noktaların makine tarafından okunabilir listesi |\n| `GET /endpoints?format=text` | Düz metin uç nokta listesi |\n| `GET /openapi.json` | OpenAPI 3.0 belirtimi |\n| `GET /help` | Tam API dokümantasyonu (HTML) |\n| `GET /help?format=json` | JSON olarak API docs |\n| `GET /docs` | Dokümantasyon sistemi (HTML) |\n| `GET /docs?format=json` | Dokümantasyon dizini (JSON) |\n| `GET /docs?format=text&scope=all` | Tüm docs tek metin bloğu olarak |\n| `GET /playground` | Etkileşimli API playground |\n\n## Hız Sınırları\n\n| Kimlik Doğrulama Yöntemi | Sınır |\n|-------------|-------|\n| Mind Key (header) | Yok |\n| Mind Key (?key=) | IP başına 60/dakika |\n| JWT (header) | Yok |\n| Herkese açık uç noktalar | Yok |\n\nHız sınırına takılan yanıtlar şunları içerir:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Sayfalama\n\nListe uç noktaları `?limit=` ve `?offset=` destekler:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nVarsayılan sınır: 100. Maksimum sınır: 500.\n\n## CORS\n\nTüm uç noktalar tarayıcı tabanlı istemciler için CORS'u destekler:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK'lar & İstemciler\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **HTTP istemcisi**: herhangi bir HTTP kütüphanesi (curl, fetch, axios vb.)\n\n## Sonraki Adımlar\n\n- [Memory API](/docs/api/memory) — en önemli uç noktalar\n- [Chat API](/docs/api/chat) — asenkron insan-ajan iletişimi\n- [Hatalar & Hata Yönetimi](/docs/api/errors)\n","content_html":"

API Genel Bakış & Temel URL

\n

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.

\n

Temel URL

\n
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.

\n

Kimlik Doğrulama

\n

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

\n
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints\nAuthorization: Bearer YOUR_JWT          # for account endpoints

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

\n
?key=YOUR_MIND_KEY

Detaylar için bkz. Kimlik Doğrulama.

\n

Uç Nokta Grupları

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GrupKimlik DoğrulamaAçıklama
PublicYokAçılış sayfası, sağlık, OpenAPI, docs
MemoryMind KeyCRUD, arama, senkronizasyon, gömmeler
ChatMind Key / JWTİnsan ve ajan arasında asenkron mesajlaşma
TasksMind KeyGörev yönetimi
ScriptsMind Key / JWTKalıcı betik deposu
SchedulerMind KeyCron işleri + değişkenler
WebhooksMind KeyOlaylarda HTTP geri aramaları
ComputersMind Key / JWTUzak bilgisayar kontrolü
User/MindsJWTHesap + mind yönetimi
SharingJWTKullanıcılar arası mind paylaşımı
PushJWTWeb Push abonelikleri
ToolsYokSaat, hesap, rastgele (herkese açık yardımcılar)
\n

Yanıt Biçimleri

\n\n

Standart Yanıt Zarfı

\n

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

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

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

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
`docs` alanı, yaygın hatalar için ilgili dokümantasyona bağlantı verir.

HTTP Durum Kodları

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

Keşfedilebilirlik Uç Noktaları

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Uç NoktaAmaç
GET /Açılış sayfası (LLM için optimize edilmiş)
GET /endpointsTüm uç noktaların makine tarafından okunabilir listesi
GET /endpoints?format=textDüz metin uç nokta listesi
GET /openapi.jsonOpenAPI 3.0 belirtimi
GET /helpTam API dokümantasyonu (HTML)
GET /help?format=jsonJSON olarak API docs
GET /docsDokümantasyon sistemi (HTML)
GET /docs?format=jsonDokümantasyon dizini (JSON)
GET /docs?format=text&scope=allTüm docs tek metin bloğu olarak
GET /playgroundEtkileşimli API playground
\n

Hız Sınırları

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

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Sayfalama

\n

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

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

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

\n

CORS

\n

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

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

SDK'lar & İstemciler

\n\n

Sonraki Adımlar

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}