{"title":"FAQ API","slug":"api-faq","category":"faq","summary":"Pertanyaan API umum — autentikasi, rate limits, penanganan error, penemuan endpoint.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":378,"read_minutes":2,"lang":"id","translated":true,"requested_lang":"id","content_markdown":"\n# FAQ API\n\nPertanyaan umum tentang API Synapse.\n\n## Bagaimana cara saya melakukan autentikasi?\n\nDua metode:\n\n1. **Mind Key** (untuk endpoint data): `Authorization: Bearer mk_...`\n2. **JWT** (untuk endpoint akun): `Authorization: Bearer eyJ...`\n\nAtau melalui parameter query (batas 60 req/menit): `?key=mk_...`\n\nLihat [Autentikasi](/docs/getting-started/authentication).\n\n## Apa perbedaan antara Mind Key dan JWT?\n\n- **Mind Key**: cakupan tenant, tidak pernah kedaluwarsa, untuk data memori/chat/tugas\n- **JWT**: cakupan pengguna, kedaluwarsa 7 hari, untuk manajemen akun/mind\n\nLihat [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Mengapa saya mendapat 401 Unauthorized?\n\nPenyebab umum:\n\n1. Header `Authorization` tidak ada\n2. Mind Key tidak valid (verifikasi dimulai dengan `mk_`)\n3. Menggunakan JWT di mana Mind Key diperlukan (atau sebaliknya)\n4. Mind Key telah dicabut\n\n**Perbaikan:** Verifikasi token Anda. Lihat [Autentikasi](/docs/getting-started/authentication).\n\n## Mengapa saya mendapat 404 Not Found?\n\nAnda menggunakan path endpoint yang salah. Synapse hanya memiliki path yang\ntercantum di `GET /endpoints`.\n\n**Perbaikan:** Panggil `GET /endpoints` untuk melihat semua path yang valid. Jangan menebak.\n\n## Mengapa saya mendapat 429 Too Many Requests?\n\nAnda menggunakan autentikasi parameter query `?key=`, yang di-rate-limit ke 60/menit.\n\n**Perbaikan:** Beralih ke header `Authorization: Bearer` (tanpa rate limit).\n\nLihat [Rate Limits](/docs/api/rate-limits).\n\n## Bagaimana cara mendaftar semua endpoint?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Bagaimana cara menemukan endpoint yang tepat?\n\n1. Periksa `GET /endpoints` untuk daftar yang dapat dibaca mesin\n2. Periksa `GET /help` untuk dokumentasi API lengkap\n3. Telusuri `GET /docs` untuk sistem dokumentasi\n4. Gunakan `GET /openapi.json` untuk spesifikasi OpenAPI 3.0\n\n## Bisakah saya menggunakan GET alih-alih POST?\n\nBeberapa endpoint POST memiliki padanan GET untuk alat yang hanya menggunakan URL:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nPeriksa `GET /endpoints` untuk varian GET yang tersedia.\n\n## Bagaimana cara saya menangani error?\n\nSemua error mengembalikan JSON:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\nLihat [Errors & Error Handling](/docs/api/errors).\n\n## Berapa batas body permintaan?\n\n10 MB. Untuk payload yang lebih besar (mis. unggahan file), gunakan endpoint multipart.\n\n## Apakah API mendukung CORS?\n\nYa. Semua endpoint mengembalikan:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## Apakah ada SDK?\n\nYa:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nLihat [Ikhtisar API](/docs/api/overview) untuk detail.\n\n## Bagaimana cara melakukan paginasi?\n\nGunakan `?limit=` dan `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nLimit default: 100. Maksimum: 500.\n\n## Bisakah saya memfilter memori berdasarkan kategori atau tag?\n\nYa:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Bagaimana cara mencari memori?\n\nDua cara:\n\n1. **Pencarian kata kunci FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Pencarian semantik**: `GET /memory/semantic-search?q=container+orchestration`\n\nLihat [Pencarian FTS5](/docs/concepts/fts5-search) dan [Pencarian Semantik](/docs/concepts/semantic-search).\n\n## Bagaimana cara memperbarui memori?\n\nPOST `/memory` dengan `category` + `key` yang sama — memori yang ada\ndiperbarui, tidak diduplikasi.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Bagaimana cara menghapus memori?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Bisakah saya menghapus secara massal?\n\nYa:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Langkah Berikutnya\n\n- [Ikhtisar API](/docs/api/overview)\n- [Errors & Error Handling](/docs/api/errors)\n- [Autentikasi](/docs/getting-started/authentication)\n","content_html":"

FAQ API

\n

Pertanyaan umum tentang API Synapse.

\n

Bagaimana cara saya melakukan autentikasi?

\n

Dua metode:

\n
    \n
  1. Mind Key (untuk endpoint data): Authorization: Bearer mk_...
    2. \n
  2. JWT (untuk endpoint akun): Authorization: Bearer eyJ...
    3. \n
\n

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

\n

Lihat Autentikasi.

\n

Apa perbedaan antara Mind Key dan JWT?

\n\n

Lihat Mind Key vs JWT.

\n

Mengapa saya mendapat 401 Unauthorized?

\n

Penyebab umum:

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

Perbaikan: Verifikasi token Anda. Lihat Autentikasi.

\n

Mengapa saya mendapat 404 Not Found?

\n

Anda menggunakan path endpoint yang salah. Synapse hanya memiliki path yang\ntercantum di GET /endpoints.

\n

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

\n

Mengapa saya mendapat 429 Too Many Requests?

\n

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

\n

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

\n

Lihat Rate Limits.

\n

Bagaimana cara mendaftar semua endpoint?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Bagaimana cara menemukan endpoint yang tepat?

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

Bisakah saya menggunakan GET alih-alih POST?

\n

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

\n\n

Periksa GET /endpoints untuk varian GET yang tersedia.

\n

Bagaimana cara saya menangani error?

\n

Semua error mengembalikan JSON:

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

Lihat Errors & Error Handling.

\n

Berapa batas body permintaan?

\n

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

\n

Apakah API mendukung CORS?

\n

Ya. Semua endpoint mengembalikan:

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

Apakah ada SDK?

\n

Ya:

\n\n

Lihat Ikhtisar API untuk detail.

\n

Bagaimana cara melakukan paginasi?

\n

Gunakan ?limit= dan ?offset=:

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

Limit default: 100. Maksimum: 500.

\n

Bisakah saya memfilter memori berdasarkan kategori atau tag?

\n

Ya:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Bagaimana cara mencari memori?

\n

Dua cara:

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

Lihat Pencarian FTS5 dan Pencarian Semantik.

\n

Bagaimana cara memperbarui memori?

\n

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

\n
# Initial store\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Bagaimana cara menghapus memori?

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

Bisakah saya menghapus secara massal?

\n

Ya:

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

Langkah Berikutnya

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}