Tổng quan API & Base URL

beginner 🤖 Thân thiện với LLM 3 phút · 688 từ Cập nhật: 2026-06-27 Tiếng Việt

Tất cả endpoint API Synapse, base URL, mẫu xác thực và định dạng phản hồi trong một glance.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM

Tổng quan API & Base URL

Synapse API là HTTP API RESTful. Tất cả endpoint trả về JSON (trừ khi có ghi chú). Trang này bao gồm những điều thiết yếu bạn cần biết trước khi đi sâu vào các endpoint cụ thể.

Base URL

https://synapse.schaefer.zone

Tất cả đường dẫn trong tài liệu này đều tương đối với base URL này. Đối với các thể hiện self-hosted, thay bằng URL của bạn.

Xác thực

Hai phương thức, cả hai đều gửi qua header Authorization:

Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints

Hoặc qua tham số query (giới hạn 60/phút):

?key=YOUR_MIND_KEY

Xem Xác thực để biết chi tiết.

Nhóm endpoint

Nhóm	Xác thực	Mô tả
Public	Không	Trang chủ, health, OpenAPI, docs
Memory	Mind Key	CRUD, tìm kiếm, đồng bộ, embeddings
Chat	Mind Key / JWT	Nhắn tin bất đồng bộ giữa con người và agent
Tasks	Mind Key	Quản lý tác vụ
Scripts	Mind Key / JWT	Lưu trữ script cố định
Scheduler	Mind Key	Cron job + biến
Webhooks	Mind Key	HTTP callback khi có sự kiện
Computers	Mind Key / JWT	Điều khiển máy tính từ xa
User/Minds	JWT	Tài khoản + quản lý mind
Sharing	JWT	Chia sẻ mind giữa người dùng
Push	JWT	Đăng ký Web Push
Tools	Không	Thời gian, calc, random (tiện ích công khai)

Định dạng phản hồi

JSON (mặc định): { "key": "value", ... }
Văn bản thuần: /memory/recall trả về văn bản tối ưu cho LLM
HTML: /, /docs, /human, /support, /playground

Envelope phản hồi chuẩn

Phản hồi thành công trả về dữ liệu trực tiếp:

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

Phản hồi lỗi sử dụng định dạng này:

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

Trường `docs` liên kết tới tài liệu liên quan cho các lỗi phổ biến.

Mã trạng thái HTTP

Mã	Ý nghĩa
200	Thành công (GET, PUT)
201	Đã tạo (POST)
204	Không có nội dung (DELETE)
400	Yêu cầu sai (lỗi validation)
401	Không được ủy quyền (thiếu/sai token)
403	Bị cấm (sai loại token)
404	Không tìm thấy (đường dẫn không tồn tại)
409	Xung đột (trùng lặp)
429	Quá nhiều yêu cầu (giới hạn tốc độ)
500	Lỗi server

Endpoint khám phá

Endpoint	Mục đích
`GET /`	Trang chủ (tối ưu cho LLM)
`GET /endpoints`	Danh sách đọc được bằng máy của tất cả endpoint
`GET /endpoints?format=text`	Danh sách endpoint dạng văn bản thuần
`GET /openapi.json`	Đặc tả OpenAPI 3.0
`GET /help`	Tài liệu API đầy đủ (HTML)
`GET /help?format=json`	Tài liệu API dạng JSON
`GET /docs`	Hệ thống tài liệu (HTML)
`GET /docs?format=json`	Mục lục tài liệu (JSON)
`GET /docs?format=text&scope=all`	Tất cả tài liệu trong một khối văn bản
`GET /playground`	Playground API tương tác

Giới hạn tốc độ

Phương thức xác thực	Giới hạn
Mind Key (header)	Không
Mind Key (?key=)	60/phút mỗi IP
JWT (header)	Không
Endpoint công khai	Không

Phản hồi bị giới hạn tốc độ bao gồm:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)

Phân trang

Endpoint dạng danh sách hỗ trợ ?limit= và ?offset=:

GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending

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

CORS

Tất cả endpoint hỗ trợ CORS cho client dựa trên trình duyệt:

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 & Client

Node.js SDK: npm install synapse-memory-sdk (repo)
MCP Server: npx -y synapse-mcp-api@latest (repo)
HTTP client: bất kỳ thư viện HTTP nào (curl, fetch, axios, v.v.)

Bước tiếp theo

Memory API — các endpoint quan trọng nhất
Chat API — giao tiếp bất đồng bộ giữa con người và agent
Lỗi & Xử lý lỗi