Ikhtisar API & Base URL

beginner 🤖 Ramah LLM 3 mnt · 548 kata Diperbarui: 2026-06-27 Bahasa Indonesia

Semua endpoint API Synapse, base URL, pola autentikasi, dan format respons dalam sekali pandang.

Baca artikel ini sebagai: 📄 Teks biasa ⚡ JSON 🤖 Format LLM

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

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

Respons error menggunakan format ini:

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

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)
MCP Server: npx -y synapse-mcp-api@latest (repo)
HTTP client: pustaka HTTP apa pun (curl, fetch, axios, dll.)

Langkah Berikutnya

Memory API — endpoint terpenting
Chat API — komunikasi asinkron manusia-agen
Errors & Error Handling