# FAQ API

Pertanyaan umum tentang API Synapse.

## Bagaimana cara saya melakukan autentikasi?

Dua metode:

1. **Mind Key** (untuk endpoint data): `Authorization: Bearer mk_...`
2. **JWT** (untuk endpoint akun): `Authorization: Bearer eyJ...`

Atau melalui parameter query (batas 60 req/menit): `?key=mk_...`

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

## Apa perbedaan antara Mind Key dan JWT?

- **Mind Key**: cakupan tenant, tidak pernah kedaluwarsa, untuk data memori/chat/tugas
- **JWT**: cakupan pengguna, kedaluwarsa 7 hari, untuk manajemen akun/mind

Lihat [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).

## Mengapa saya mendapat 401 Unauthorized?

Penyebab umum:

1. Header `Authorization` tidak ada
2. Mind Key tidak valid (verifikasi dimulai dengan `mk_`)
3. Menggunakan JWT di mana Mind Key diperlukan (atau sebaliknya)
4. Mind Key telah dicabut

**Perbaikan:** Verifikasi token Anda. Lihat [Autentikasi](/docs/getting-started/authentication).

## Mengapa saya mendapat 404 Not Found?

Anda menggunakan path endpoint yang salah. Synapse hanya memiliki path yang
tercantum di `GET /endpoints`.

**Perbaikan:** Panggil `GET /endpoints` untuk melihat semua path yang valid. Jangan menebak.

## Mengapa saya mendapat 429 Too Many Requests?

Anda menggunakan autentikasi parameter query `?key=`, yang di-rate-limit ke 60/menit.

**Perbaikan:** Beralih ke header `Authorization: Bearer` (tanpa rate limit).

Lihat [Rate Limits](/docs/api/rate-limits).

## Bagaimana cara mendaftar semua endpoint?

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

## Bagaimana cara menemukan endpoint yang tepat?

1. Periksa `GET /endpoints` untuk daftar yang dapat dibaca mesin
2. Periksa `GET /help` untuk dokumentasi API lengkap
3. Telusuri `GET /docs` untuk sistem dokumentasi
4. Gunakan `GET /openapi.json` untuk spesifikasi OpenAPI 3.0

## Bisakah saya menggunakan GET alih-alih POST?

Beberapa endpoint POST memiliki padanan GET untuk alat yang hanya menggunakan URL:

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

Periksa `GET /endpoints` untuk varian GET yang tersedia.

## Bagaimana cara saya menangani error?

Semua error mengembalikan JSON:

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

Lihat [Errors & Error Handling](/docs/api/errors).

## Berapa batas body permintaan?

10 MB. Untuk payload yang lebih besar (mis. unggahan file), gunakan endpoint multipart.

## Apakah API mendukung CORS?

Ya. Semua endpoint mengembalikan:

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

## Apakah ada SDK?

Ya:

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

Lihat [Ikhtisar API](/docs/api/overview) untuk detail.

## Bagaimana cara melakukan paginasi?

Gunakan `?limit=` dan `?offset=`:

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

Limit default: 100. Maksimum: 500.

## Bisakah saya memfilter memori berdasarkan kategori atau tag?

Ya:

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

## Bagaimana cara mencari memori?

Dua cara:

1. **Pencarian kata kunci FTS5**: `GET /memory/search?q=docker+swarm`
2. **Pencarian semantik**: `GET /memory/semantic-search?q=container+orchestration`

Lihat [Pencarian FTS5](/docs/concepts/fts5-search) dan [Pencarian Semantik](/docs/concepts/semantic-search).

## Bagaimana cara memperbarui memori?

POST `/memory` dengan `category` + `key` yang sama — memori yang ada
diperbarui, tidak diduplikasi.

```bash
# 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"}'
```

## Bagaimana cara menghapus memori?

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

## Bisakah saya menghapus secara massal?

Ya:

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

## Langkah Berikutnya

- [Ikhtisar API](/docs/api/overview)
- [Errors & Error Handling](/docs/api/errors)
- [Autentikasi](/docs/getting-started/authentication)