# Tổng quan API & Base URL
SUMMARY: 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.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

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
[CODE BLOCK]
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 :
[CODE BLOCK]
Hoặc qua tham số query (giới hạn 60/phút):
[CODE BLOCK]
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): 
- Văn bản thuần:  trả về văn bản tối ưu cho LLM
- HTML: , , , , 
Envelope phản hồi chuẩn
Phản hồi thành công trả về dữ liệu trực tiếp:
[CODE BLOCK]
Phản hồi lỗi sử dụng định dạng này:
[CODE BLOCK]
> [!NOTE]
> Trường  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 |
|----------|---------|
|  | Trang chủ (tối ưu cho LLM) |
|  | Danh sách đọc được bằng máy của tất cả endpoint |
|  | Danh sách endpoint dạng văn bản thuần |
|  | Đặc tả OpenAPI 3.0 |
|  | Tài liệu API đầy đủ (HTML) |
|  | Tài liệu API dạng JSON |
|  | Hệ thống tài liệu (HTML) |
|  | Mục lục tài liệu (JSON) |
|  | Tất cả tài liệu trong một khối văn bản |
|  | 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:
[CODE BLOCK]
Phân trang
Endpoint dạng danh sách hỗ trợ  và :
[CODE BLOCK]
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:
[CODE BLOCK]
SDK & Client
- Node.js SDK:  (repo)
- MCP Server:  (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