{"title":"API SSS","slug":"api-faq","category":"faq","summary":"Yaygın API soruları — kimlik doğrulama, hız sınırları, hata yönetimi, uç nokta keşfi.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":363,"read_minutes":2,"lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# API SSS\n\nSynapse API hakkında yaygın sorular.\n\n## Nasıl kimlik doğrularım?\n\nİki yöntem:\n\n1. **Mind Key** (veri uç noktaları için): `Authorization: Bearer mk_...`\n2. **JWT** (hesap uç noktaları için): `Authorization: Bearer eyJ...`\n\nVeya sorgu parametresi ile (60 istek/dakika sınırı): `?key=mk_...`\n\nBkz. [Kimlik Doğrulama](/docs/getting-started/authentication).\n\n## Mind Key ve JWT arasındaki fark nedir?\n\n- **Mind Key**: kiracı kapsamlı, asla sona ermez, memory/chat/tasks verileri için\n- **JWT**: kullanıcı kapsamlı, 7 günlük son kullanma, hesap/mind yönetimi için\n\nBkz. [Mind Key ve JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Neden 401 Unauthorized alıyorum?\n\nYaygın nedenler:\n\n1. `Authorization` başlığı eksik\n2. Geçersiz Mind Key (`mk_` ile başladığını doğrulayın)\n3. Mind Key gerekendiye JWT kullanma (veya tersi)\n4. Mind Key iptal edilmiş\n\n**Çözüm:** Token'ınızı doğrulayın. Bkz. [Kimlik Doğrulama](/docs/getting-started/authentication).\n\n## Neden 404 Not Found alıyorum?\n\nYanlış bir uç nokta yolu kullandınız. Synapse'te yalnızca `GET /endpoints` içinde listelenen yollar mevcuttur.\n\n**Çözüm:** Tüm geçerli yolları görmek için `GET /endpoints` çağırın. Tahmin etmeyin.\n\n## Neden 429 Too Many Requests alıyorum?\n\n`?key=` sorgu parametresi kimlik doğrulaması kullanıyorsunuz, bu da 60/dakika ile sınırlıdır.\n\n**Çözüm:** `Authorization: Bearer` başlığına geçin (hız sınırı yok).\n\nBkz. [Hız Sınırları](/docs/api/rate-limits).\n\n## Tüm uç noktaları nasıl listelerim?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Doğru uç noktayı nasıl bulurum?\n\n1. Makine tarafından okunabilir liste için `GET /endpoints` kontrol edin\n2. Tam API docs için `GET /help` kontrol edin\n3. Dokümantasyon sistemi için `GET /docs` göz atın\n4. OpenAPI 3.0 spec için `GET /openapi.json` kullanın\n\n## POST yerine GET kullanabilir miyim?\n\nBazı POST uç noktalarının yalnızca URL kullanan araçlar için GET karşılığı vardır:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nMevcut GET varyantları için `GET /endpoints` kontrol edin.\n\n## Hataları nasıl ele alırım?\n\nTüm hatalar JSON döndürü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\nBkz. [Hatalar & Hata Yönetimi](/docs/api/errors).\n\n## İstek gövdesi sınırı nedir?\n\n10 MB. Daha büyük yükler için (örn. dosya yüklemeleri) multipart uç noktalarını kullanın.\n\n## API CORS destekliyor mu?\n\nEvet. Tüm uç noktalar şunu döndürür:\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\n```\n\n## Bir SDK var mı?\n\nEvet:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nDetaylar için bkz. [API Genel Bakış](/docs/api/overview).\n\n## Nasıl sayfalandırırım?\n\n`?limit=` ve `?offset=` kullanın:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nVarsayılan sınır: 100. Maksimum: 500.\n\n## Bellekleri kategoriye veya etikete göre filtreleyebilir miyim?\n\nEvet:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Bellekleri nasıl ararım?\n\nİki yol:\n\n1. **FTS5 anahtar kelime arama**: `GET /memory/search?q=docker+swarm`\n2. **Anlamsal arama**: `GET /memory/semantic-search?q=container+orchestration`\n\nBkz. [FTS5 Arama](/docs/concepts/fts5-search) ve [Anlamsal Arama](/docs/concepts/semantic-search).\n\n## Bir belleği nasıl güncellerim?\n\nAynı `category` + `key` ile `POST /memory` — mevcut bellek güncellenir, çoğaltılmaz.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Bir belleği nasıl silerim?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Toplu silebilir miyim?\n\nEvet:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Sonraki Adımlar\n\n- [API Genel Bakış](/docs/api/overview)\n- [Hatalar & Hata Yönetimi](/docs/api/errors)\n- [Kimlik Doğrulama](/docs/getting-started/authentication)\n","content_html":"

API SSS

\n

Synapse API hakkında yaygın sorular.

\n

Nasıl kimlik doğrularım?

\n

İki yöntem:

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

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

\n

Bkz. Kimlik Doğrulama.

\n

Mind Key ve JWT arasındaki fark nedir?

\n\n

Bkz. Mind Key ve JWT.

\n

Neden 401 Unauthorized alıyorum?

\n

Yaygın nedenler:

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

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

\n

Neden 404 Not Found alıyorum?

\n

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

\n

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

\n

Neden 429 Too Many Requests alıyorum?

\n

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

\n

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

\n

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

\n

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

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

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

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

POST yerine GET kullanabilir miyim?

\n

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

\n\n

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

\n

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

\n

Tüm hatalar JSON döndürü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}

Bkz. Hatalar & Hata Yönetimi.

\n

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

\n

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

\n

API CORS destekliyor mu?

\n

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

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

Bir SDK var mı?

\n

Evet:

\n\n

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

\n

Nasıl sayfalandırırım?

\n

?limit= ve ?offset= kullanın:

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

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

\n

Bellekleri kategoriye veya etikete göre filtreleyebilir miyim?

\n

Evet:

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

Bellekleri nasıl ararım?

\n

İki yol:

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

Bkz. FTS5 Arama ve Anlamsal Arama.

\n

Bir belleği nasıl güncellerim?

\n

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

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

Bir belleği nasıl silerim?

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

Toplu silebilir miyim?

\n

Evet:

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

Sonraki Adımlar

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