# Ikhtisar API & Base URL

Synapse API adalah HTTP API yang RESTful. Semua endpoint mengembalikan JSON
(kecuali jika dicatat). Halaman ini mencakup hal-hal penting yang perlu Anda
ketahui sebelum mendalami endpoint tertentu.

## Base URL

```
https://synapse.schaefer.zone
```

Semua path dalam dokumentasi ini relatif terhadap base URL ini. Untuk instansi
self-hosted, ganti dengan URL Anda sendiri.

## Autentikasi

Dua metode, keduanya dikirim melalui header `Authorization`:

```
Authorization: Bearer YOUR_MIND_KEY    # untuk endpoint data
Authorization: Bearer YOUR_JWT          # untuk endpoint akun
```

Atau melalui parameter query (rate-limited ke 60/menit):

```
?key=YOUR_MIND_KEY
```

Lihat [Autentikasi](/docs/getting-started/authentication) untuk detailnya.

## Grup Endpoint

| Grup | Auth | Deskripsi |
|-------|------|-------------|
| Public | Tidak ada | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, pencarian, sinkronisasi, embeddings |
| Chat | Mind Key / JWT | Pesan asinkron antara manusia dan agen |
| Tasks | Mind Key | Manajemen tugas |
| Scripts | Mind Key / JWT | Penyimpanan skrip persisten |
| Scheduler | Mind Key | Cron jobs + variabel |
| Webhooks | Mind Key | HTTP callback pada event |
| Computers | Mind Key / JWT | Kontrol komputer remote |
| User/Minds | JWT | Akun + manajemen mind |
| Sharing | JWT | Berbagi mind antar pengguna |
| Push | JWT | Langganan Web Push |
| Tools | Tidak ada | Waktu, kalkulator, acak (utilitas publik) |

## Format Respons

- **JSON** (default): `{ "key": "value", ... }`
- **Teks polos**: `/memory/recall` mengembalikan teks yang dioptimalkan untuk LLM
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Amplop Respons Standar

Respons sukses mengembalikan data secara langsung:

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

Respons error menggunakan format ini:

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

> [!NOTE]
> Field `docs` menautkan ke dokumentasi terkait untuk error umum.

## Kode Status HTTP

| Kode | Arti |
|------|---------|
| 200 | Sukses (GET, PUT) |
| 201 | Created (POST) |
| 204 | No content (DELETE) |
| 400 | Bad request (error validasi) |
| 401 | Unauthorized (token tidak ada/tidak valid) |
| 403 | Forbidden (tipe token salah) |
| 404 | Not found (path tidak ada) |
| 409 | Conflict (duplikat) |
| 429 | Too many requests (rate limit) |
| 500 | Server error |

## Endpoint Discoverability

| Endpoint | Tujuan |
|----------|---------|
| `GET /` | Landing page (dioptimalkan untuk LLM) |
| `GET /endpoints` | Daftar yang dapat dibaca mesin dari semua endpoint |
| `GET /endpoints?format=text` | Daftar endpoint teks polos |
| `GET /openapi.json` | Spesifikasi OpenAPI 3.0 |
| `GET /help` | Dokumentasi API lengkap (HTML) |
| `GET /help?format=json` | Dokumentasi API sebagai JSON |
| `GET /docs` | Sistem dokumentasi (HTML) |
| `GET /docs?format=json` | Indeks dokumentasi (JSON) |
| `GET /docs?format=text&scope=all` | Semua dokumentasi sebagai satu blok teks |
| `GET /playground` | Playground API interaktif |

## Rate Limits

| Metode Auth | Batas |
|-------------|-------|
| Mind Key (header) | Tidak ada |
| Mind Key (?key=) | 60/menit per IP |
| JWT (header) | Tidak ada |
| Endpoint publik | Tidak ada |

Respons yang di-rate-limit menyertakan:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (hanya saat 429)
```

## Paginasi

Endpoint daftar mendukung `?limit=` dan `?offset=`:

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

Limit default: 100. Limit maksimum: 500.

## CORS

Semua endpoint mendukung CORS untuk klien berbasis browser:

```
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 & Klien

- **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 client**: pustaka HTTP apa pun (curl, fetch, axios, dll.)

## Langkah Berikutnya

- [Memory API](/docs/api/memory) — endpoint terpenting
- [Chat API](/docs/api/chat) — komunikasi asinkron manusia-agen
- [Errors & Error Handling](/docs/api/errors)