# 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](/docs/getting-started/authentication).

## 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:

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

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

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

> [!NOTE]
> `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](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP istemcisi**: herhangi bir HTTP kütüphanesi (curl, fetch, axios vb.)

## Sonraki Adımlar

- [Memory API](/docs/api/memory) — en önemli uç noktalar
- [Chat API](/docs/api/chat) — asenkron insan-ajan iletişimi
- [Hatalar & Hata Yönetimi](/docs/api/errors)