# 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](/docs/getting-started/authentication) để 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:

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

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

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

> [!NOTE]
> 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](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP client**: bất kỳ thư viện HTTP nào (curl, fetch, axios, v.v.)

## Bước tiếp theo

- [Memory API](/docs/api/memory) — các endpoint quan trọng nhất
- [Chat API](/docs/api/chat) — giao tiếp bất đồng bộ giữa con người và agent
- [Lỗi & Xử lý lỗi](/docs/api/errors)