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.

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.

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.

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.

Bagaimana cara mendaftar semua endpoint?

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:

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

Lihat Errors & Error Handling.

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 untuk detail.

Bagaimana cara melakukan paginasi?

Gunakan ?limit= dan ?offset=:

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

Limit default: 100. Maksimum: 500.

Bisakah saya memfilter memori berdasarkan kategori atau tag?

Ya:

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 dan Pencarian Semantik.

Bagaimana cara memperbarui memori?

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

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

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

Bisakah saya menghapus secara massal?

Ya:

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

Langkah Berikutnya

• Ikhtisar API
• Errors & Error Handling
• Autentikasi