คำถามที่พบบ่อยเกี่ยวกับ API

คำถามทั่วไปเกี่ยวกับ Synapse API

ฉันยืนยันตัวตนอย่างไร?

สองวิธี:

1. Mind Key (สำหรับ endpoint ข้อมูล): Authorization: Bearer mk_...
2. JWT (สำหรับ endpoint บัญชี): Authorization: Bearer eyJ...

หรือผ่าน query parameter (จำกัด 60 req/min): ?key=mk_...

ดู Authentication

ความแตกต่างระหว่าง Mind Key และ JWT คืออะไร?

• Mind Key: tenant-scoped, ไม่หมดอายุ, สำหรับข้อมูล memory/chat/tasks
• JWT: user-scoped, หมดอายุ 7 วัน, สำหรับการจัดการบัญชี/mind

ดู Mind Key vs JWT

ทำไมฉันได้ 401 Unauthorized?

สาเหตุทั่วไป:

1. ขาด Authorization header
2. Mind Key ไม่ถูกต้อง (ตรวจว่าขึ้นต้นด้วย mk_)
3. ใช้ JWT ในที่ที่ต้องใช้ Mind Key (หรือกลับกัน)
4. Mind Key ถูกเพิกถอน

วิธีแก้: ตรวจสอบ token ของคุณ ดู Authentication

ทำไมฉันได้ 404 Not Found?

คุณใช้ endpoint path ผิด Synapse มีเพียง path ที่แสดงใน GET /endpoints

วิธีแก้: เรียก GET /endpoints เพื่อดู path ที่ถูกต้องทั้งหมด อย่าเดา

ทำไมฉันได้ 429 Too Many Requests?

คุณใช้ auth ผ่าน ?key= query parameter ซึ่งจำกัดที่ 60/min

วิธีแก้: เปลี่ยนไปใช้ Authorization: Bearer header (ไม่จำกัดอัตรา)

ดู Rate Limits

ฉันจะระบุ endpoint ทั้งหมดได้อย่างไร?

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

ฉันจะหา endpoint ที่เหมาะสมได้อย่างไร?

1. ตรวจ GET /endpoints สำหรับรายการ machine-readable
2. ตรวจ GET /help สำหรับ API docs แบบเต็ม
3. ดู GET /docs สำหรับระบบเอกสาร
4. ใช้ GET /openapi.json สำหรับ OpenAPI 3.0 spec

ฉันใช้ GET แทน POST ได้ไหม?

POST endpoint บางตัวมี GET equivalent สำหรับเครื่องมือ URL-only:

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

ตรวจ GET /endpoints สำหรับ GET variant ที่มี

ฉันจัดการ error อย่างไร?

error ทั้งหมดส่งกลับเป็น JSON:

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

ดู Errors & Error Handling

ขีดจำกัดขนาด request body คือเท่าไร?

10 MB สำหรับ payload ที่ใหญ่กว่า (เช่น อัปโหลดไฟล์) ให้ใช้ multipart endpoint

API รองรับ CORS ไหม?

ใช่ ทุก endpoint ส่งกลับ:

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

มี SDK ไหม?

มี:

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

ดูรายละเอียดที่ API Overview

ฉันทำ pagination อย่างไร?

ใช้ ?limit= และ ?offset=:

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

Limit เริ่มต้น: 100 สูงสุด: 500

ฉันกรอง memory ตาม category หรือ tag ได้ไหม?

ได้:

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

ฉันค้นหา memory อย่างไร?

สองวิธี:

1. FTS5 keyword search: GET /memory/search?q=docker+swarm
2. Semantic search: GET /memory/semantic-search?q=container+orchestration

ดู FTS5 Search และ Semantic Search

ฉันอัปเดต memory อย่างไร?

POST /memory ด้วย category + key เดิม — memory ที่มีอยู่จะถูกอัปเดต ไม่ซ้ำ

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

ฉันลบ memory อย่างไร?

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

ลบเป็นจำนวนมากได้ไหม?

ได้:

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

ขั้นตอนถัดไป

• API Overview
• Errors & Error Handling
• Authentication