{"title":"Tổng quan API & Base URL","slug":"overview","category":"api","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.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":688,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Tổng quan API & Base URL\n\nSynapse API là HTTP API RESTful. Tất cả endpoint trả về JSON (trừ khi có ghi\nchú). 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\ncác endpoint cụ thể.\n\n## Base URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nTấ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\ncác thể hiện self-hosted, thay bằng URL của bạn.\n\n## Xác thực\n\nHai phương thức, cả hai đều gửi qua header `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # for data endpoints\nAuthorization: Bearer YOUR_JWT # for account endpoints\n```\n\nHoặc qua tham số query (giới hạn 60/phút):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nXem [Xác thực](/docs/getting-started/authentication) để biết chi tiết.\n\n## Nhóm endpoint\n\n| Nhóm | Xác thực | Mô tả |\n|-------|------|-------------|\n| Public | Không | Trang chủ, health, OpenAPI, docs |\n| Memory | Mind Key | CRUD, tìm kiếm, đồng bộ, embeddings |\n| Chat | Mind Key / JWT | Nhắn tin bất đồng bộ giữa con người và agent |\n| Tasks | Mind Key | Quản lý tác vụ |\n| Scripts | Mind Key / JWT | Lưu trữ script cố định |\n| Scheduler | Mind Key | Cron job + biến |\n| Webhooks | Mind Key | HTTP callback khi có sự kiện |\n| Computers | Mind Key / JWT | Điều khiển máy tính từ xa |\n| User/Minds | JWT | Tài khoản + quản lý mind |\n| Sharing | JWT | Chia sẻ mind giữa người dùng |\n| Push | JWT | Đăng ký Web Push |\n| Tools | Không | Thời gian, calc, random (tiện ích công khai) |\n\n## Định dạng phản hồi\n\n- **JSON** (mặc định): `{ \"key\": \"value\", ... }`\n- **Văn bản thuần**: `/memory/recall` trả về văn bản tối ưu cho LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Envelope phản hồi chuẩn\n\nPhản hồi thành công trả về dữ liệu trực tiếp:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nPhản hồi lỗi sử dụng định dạng này:\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\n> [!NOTE]\n> Trường `docs` liên kết tới tài liệu liên quan cho các lỗi phổ biến.\n\n## Mã trạng thái HTTP\n\n| Mã | Ý nghĩa |\n|------|---------|\n| 200 | Thành công (GET, PUT) |\n| 201 | Đã tạo (POST) |\n| 204 | Không có nội dung (DELETE) |\n| 400 | Yêu cầu sai (lỗi validation) |\n| 401 | Không được ủy quyền (thiếu/sai token) |\n| 403 | Bị cấm (sai loại token) |\n| 404 | Không tìm thấy (đường dẫn không tồn tại) |\n| 409 | Xung đột (trùng lặp) |\n| 429 | Quá nhiều yêu cầu (giới hạn tốc độ) |\n| 500 | Lỗi server |\n\n## Endpoint khám phá\n\n| Endpoint | Mục đích |\n|----------|---------|\n| `GET /` | Trang chủ (tối ưu cho LLM) |\n| `GET /endpoints` | Danh sách đọc được bằng máy của tất cả endpoint |\n| `GET /endpoints?format=text` | Danh sách endpoint dạng văn bản thuần |\n| `GET /openapi.json` | Đặc tả OpenAPI 3.0 |\n| `GET /help` | Tài liệu API đầy đủ (HTML) |\n| `GET /help?format=json` | Tài liệu API dạng JSON |\n| `GET /docs` | Hệ thống tài liệu (HTML) |\n| `GET /docs?format=json` | Mục lục tài liệu (JSON) |\n| `GET /docs?format=text&scope=all` | Tất cả tài liệu trong một khối văn bản |\n| `GET /playground` | Playground API tương tác |\n\n## Giới hạn tốc độ\n\n| Phương thức xác thực | Giới hạn |\n|-------------|-------|\n| Mind Key (header) | Không |\n| Mind Key (?key=) | 60/phút mỗi IP |\n| JWT (header) | Không |\n| Endpoint công khai | Không |\n\nPhản hồi bị giới hạn tốc độ bao gồm:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Phân trang\n\nEndpoint dạng danh sách hỗ trợ `?limit=` và `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nGiới hạn mặc định: 100. Giới hạn tối đa: 500.\n\n## CORS\n\nTất cả endpoint hỗ trợ CORS cho client dựa trên trình duyệt:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK & Client\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **HTTP client**: bất kỳ thư viện HTTP nào (curl, fetch, axios, v.v.)\n\n## Bước tiếp theo\n\n- [Memory API](/docs/api/memory) — các endpoint quan trọng nhất\n- [Chat API](/docs/api/chat) — giao tiếp bất đồng bộ giữa con người và agent\n- [Lỗi & Xử lý lỗi](/docs/api/errors)\n","content_html":"

Tổng quan API & Base URL

\n

Synapse API là HTTP API RESTful. Tất cả endpoint trả về JSON (trừ khi có ghi\nchú). 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\ncác endpoint cụ thể.

\n

Base URL

\n
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\ncác thể hiện self-hosted, thay bằng URL của bạn.

\n

Xác thực

\n

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

\n
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints\nAuthorization: Bearer YOUR_JWT          # for account endpoints

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

\n
?key=YOUR_MIND_KEY

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

\n

Nhóm endpoint

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NhómXác thựcMô tả
PublicKhôngTrang chủ, health, OpenAPI, docs
MemoryMind KeyCRUD, tìm kiếm, đồng bộ, embeddings
ChatMind Key / JWTNhắn tin bất đồng bộ giữa con người và agent
TasksMind KeyQuản lý tác vụ
ScriptsMind Key / JWTLưu trữ script cố định
SchedulerMind KeyCron job + biến
WebhooksMind KeyHTTP callback khi có sự kiện
ComputersMind Key / JWTĐiều khiển máy tính từ xa
User/MindsJWTTài khoản + quản lý mind
SharingJWTChia sẻ mind giữa người dùng
PushJWTĐăng ký Web Push
ToolsKhôngThời gian, calc, random (tiện ích công khai)
\n

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

\n\n

Envelope phản hồi chuẩn

\n

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

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

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

\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}
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

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

Endpoint khám phá

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointMục đích
GET /Trang chủ (tối ưu cho LLM)
GET /endpointsDanh sách đọc được bằng máy của tất cả endpoint
GET /endpoints?format=textDanh sách endpoint dạng văn bản thuần
GET /openapi.jsonĐặc tả OpenAPI 3.0
GET /helpTài liệu API đầy đủ (HTML)
GET /help?format=jsonTài liệu API dạng JSON
GET /docsHệ thống tài liệu (HTML)
GET /docs?format=jsonMục lục tài liệu (JSON)
GET /docs?format=text&scope=allTất cả tài liệu trong một khối văn bản
GET /playgroundPlayground API tương tác
\n

Giới hạn tốc độ

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

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Phân trang

\n

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

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

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

\n

CORS

\n

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

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

SDK & Client

\n\n

Bước tiếp theo

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