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

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

## 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 độ](/docs/api/rate-limits).

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

```bash
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:

```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](/docs/api/errors).

## 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](/docs/api/overview) để biết chi tiết.

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

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

```bash
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ó:

```bash
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](/docs/concepts/fts5-search) và [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search).

## 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.

```bash
# 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ớ?

```bash
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ó:

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

## Bước tiếp theo

- [Tổng quan API](/docs/api/overview)
- [Lỗi & Xử lý lỗi](/docs/api/errors)
- [Xác thực](/docs/getting-started/authentication)