FAQ API

Các câu hỏi phổ biến về Synapse API.

Làm thế nào để xác thực?

Hai phương thức:

1. Mind Key (cho endpoint dữ liệu): Authorization: Bearer mk_...
2. JWT (cho endpoint tài khoản): Authorization: Bearer eyJ...

Hoặc qua tham số query (giới hạn 60 yêu cầu/phút): ?key=mk_...

Xem Xác thực.

Sự khác biệt giữa Mind Key và JWT là gì?

• Mind Key: phạm vi tenant, không bao giờ hết hạn, cho dữ liệu memory/chat/tasks
• JWT: phạm vi người dùng, hết hạn sau 7 ngày, cho quản lý tài khoản/mind

Xem Mind Key vs JWT.

Tại sao tôi nhận 401 Unauthorized?

Nguyên nhân phổ biến:

1. Thiếu header Authorization
2. Mind Key không hợp lệ (xác minh nó bắt đầu bằng mk_)
3. Sử dụng JWT nơi yêu cầu Mind Key (hoặc ngược lại)
4. Mind Key đã bị thu hồi

Khắc phục: Xác minh token của bạn. Xem Xác thực.

Tại sao tôi nhận 404 Not Found?

Bạn đã dùng sai đường dẫn endpoint. Synapse chỉ có các đường dẫn liệt kê trong GET /endpoints.

Khắc phục: Gọi GET /endpoints để xem tất cả đường dẫn hợp lệ. Không đoán.

Tại sao tôi nhận 429 Too Many Requests?

Bạn đang sử dụng xác thực tham số query ?key=, bị giới hạn 60/phút.

Khắc phục: Chuyển sang header Authorization: Bearer (không giới hạn tốc độ).

Xem Giới hạn tốc độ.

Làm thế nào để liệt kê tất cả endpoint?

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

Làm thế nào để tìm đúng endpoint?

1. Kiểm tra GET /endpoints cho danh sách đọc bằng máy
2. Kiểm tra GET /help cho tài liệu API đầy đủ
3. Duyệt GET /docs cho hệ thống tài liệu
4. Sử dụng GET /openapi.json cho đặc tả OpenAPI 3.0

Tôi có thể dùng GET thay vì POST không?

Một số endpoint POST có phiên bản GET tương đương cho công cụ chỉ dùng URL:

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

Kiểm tra GET /endpoints cho các biến thể GET khả dụng.

Làm thế nào để xử lý lỗi?

Tất cả lỗi trả về JSON:

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

Xem Lỗi & Xử lý lỗi.

Giới hạn body yêu cầu là bao nhiêu?

10 MB. Cho payload lớn hơn (ví dụ tải tệp lên), sử dụng các endpoint multipart.

API có hỗ trợ CORS không?

Có. Tất cả endpoint trả về:

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

Có SDK không?

Có:

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

Xem Tổng quan API để biết chi tiết.

Làm thế nào để phân trang?

Sử dụng ?limit= và ?offset=:

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

Giới hạn mặc định: 100. Tối đa: 500.

Tôi có thể lọc bộ nhớ theo danh mục hoặc tag không?

Có:

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

Làm thế nào để tìm kiếm bộ nhớ?

Hai cách:

1. Tìm kiếm từ khóa FTS5: GET /memory/search?q=docker+swarm
2. Tìm kiếm ngữ nghĩa: GET /memory/semantic-search?q=container+orchestration

Xem Tìm kiếm FTS5 và Tìm kiếm ngữ nghĩa.

Làm thế nào để cập nhật bộ nhớ?

POST /memory với cùng category + key — bộ nhớ hiện có được cập nhật, không trùng lặp.

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

Làm thế nào để xóa bộ nhớ?

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

Tôi có thể xóa hàng loạt không?

Có:

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

Bước tiếp theo

• Tổng quan API
• Lỗi & Xử lý lỗi
• Xác thực