{"title":"FAQ API","slug":"api-faq","category":"faq","summary":"Câu hỏi API phổ biến — xác thực, giới hạn tốc độ, xử lý lỗi, khám phá endpoint.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":511,"read_minutes":3,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# FAQ API\n\nCác câu hỏi phổ biến về Synapse API.\n\n## Làm thế nào để xác thực?\n\nHai phương thức:\n\n1. **Mind Key** (cho endpoint dữ liệu): `Authorization: Bearer mk_...`\n2. **JWT** (cho endpoint tài khoản): `Authorization: Bearer eyJ...`\n\nHoặc qua tham số query (giới hạn 60 yêu cầu/phút): `?key=mk_...`\n\nXem [Xác thực](/docs/getting-started/authentication).\n\n## Sự khác biệt giữa Mind Key và JWT là gì?\n\n- **Mind Key**: phạm vi tenant, không bao giờ hết hạn, cho dữ liệu memory/chat/tasks\n- **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\n\nXem [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Tại sao tôi nhận 401 Unauthorized?\n\nNguyên nhân phổ biến:\n\n1. Thiếu header `Authorization`\n2. Mind Key không hợp lệ (xác minh nó bắt đầu bằng `mk_`)\n3. Sử dụng JWT nơi yêu cầu Mind Key (hoặc ngược lại)\n4. Mind Key đã bị thu hồi\n\n**Khắc phục:** Xác minh token của bạn. Xem [Xác thực](/docs/getting-started/authentication).\n\n## Tại sao tôi nhận 404 Not Found?\n\nBạn đã dùng sai đường dẫn endpoint. Synapse chỉ có các đường dẫn liệt kê trong\n`GET /endpoints`.\n\n**Khắc phục:** Gọi `GET /endpoints` để xem tất cả đường dẫn hợp lệ. Không đoán.\n\n## Tại sao tôi nhận 429 Too Many Requests?\n\nBạn đang sử dụng xác thực tham số query `?key=`, bị giới hạn 60/phút.\n\n**Khắc phục:** Chuyển sang header `Authorization: Bearer` (không giới hạn tốc độ).\n\nXem [Giới hạn tốc độ](/docs/api/rate-limits).\n\n## Làm thế nào để liệt kê tất cả endpoint?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Làm thế nào để tìm đúng endpoint?\n\n1. Kiểm tra `GET /endpoints` cho danh sách đọc bằng máy\n2. Kiểm tra `GET /help` cho tài liệu API đầy đủ\n3. Duyệt `GET /docs` cho hệ thống tài liệu\n4. Sử dụng `GET /openapi.json` cho đặc tả OpenAPI 3.0\n\n## Tôi có thể dùng GET thay vì POST không?\n\nMột số endpoint POST có phiên bản GET tương đương cho công cụ chỉ dùng URL:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nKiểm tra `GET /endpoints` cho các biến thể GET khả dụng.\n\n## Làm thế nào để xử lý lỗi?\n\nTất cả lỗi trả về JSON:\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\nXem [Lỗi & Xử lý lỗi](/docs/api/errors).\n\n## Giới hạn body yêu cầu là bao nhiêu?\n\n10 MB. Cho payload lớn hơn (ví dụ tải tệp lên), sử dụng các endpoint multipart.\n\n## API có hỗ trợ CORS không?\n\nCó. Tất cả endpoint trả về:\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\n```\n\n## Có SDK không?\n\nCó:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nXem [Tổng quan API](/docs/api/overview) để biết chi tiết.\n\n## Làm thế nào để phân trang?\n\nSử dụng `?limit=` và `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nGiới hạn mặc định: 100. Tối đa: 500.\n\n## Tôi có thể lọc bộ nhớ theo danh mục hoặc tag không?\n\nCó:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Làm thế nào để tìm kiếm bộ nhớ?\n\nHai cách:\n\n1. **Tìm kiếm từ khóa FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Tìm kiếm ngữ nghĩa**: `GET /memory/semantic-search?q=container+orchestration`\n\nXem [Tìm kiếm FTS5](/docs/concepts/fts5-search) và [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search).\n\n## Làm thế nào để cập nhật bộ nhớ?\n\nPOST `/memory` với cùng `category` + `key` — bộ nhớ hiện có được cập nhật, không\ntrùng lặp.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Làm thế nào để xóa bộ nhớ?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Tôi có thể xóa hàng loạt không?\n\nCó:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Bước tiếp theo\n\n- [Tổng quan API](/docs/api/overview)\n- [Lỗi & Xử lý lỗi](/docs/api/errors)\n- [Xác thực](/docs/getting-started/authentication)\n","content_html":"

FAQ API

\n

Các câu hỏi phổ biến về Synapse API.

\n

Làm thế nào để xác thực?

\n

Hai phương thức:

\n
    \n
  1. Mind Key (cho endpoint dữ liệu): Authorization: Bearer mk_...
    2. \n
  2. JWT (cho endpoint tài khoản): Authorization: Bearer eyJ...
    3. \n
\n

Hoặc qua tham số query (giới hạn 60 yêu cầu/phút): ?key=mk_...

\n

Xem Xác thực.

\n

Sự khác biệt giữa Mind Key và JWT là gì?

\n\n

Xem Mind Key vs JWT.

\n

Tại sao tôi nhận 401 Unauthorized?

\n

Nguyên nhân phổ biến:

\n
    \n
  1. Thiếu header Authorization
    2. \n
  2. Mind Key không hợp lệ (xác minh nó bắt đầu bằng mk_)
    3. \n
  3. Sử dụng JWT nơi yêu cầu Mind Key (hoặc ngược lại)
    4. \n
  4. Mind Key đã bị thu hồi
    5. \n
\n

Khắc phục: Xác minh token của bạn. Xem Xác thực.

\n

Tại sao tôi nhận 404 Not Found?

\n

Bạn đã dùng sai đường dẫn endpoint. Synapse chỉ có các đường dẫn liệt kê trong\nGET /endpoints.

\n

Khắc phục: Gọi GET /endpoints để xem tất cả đường dẫn hợp lệ. Không đoán.

\n

Tại sao tôi nhận 429 Too Many Requests?

\n

Bạn đang sử dụng xác thực tham số query ?key=, bị giới hạn 60/phút.

\n

Khắc phục: Chuyển sang header Authorization: Bearer (không giới hạn tốc độ).

\n

Xem Giới hạn tốc độ.

\n

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

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Làm thế nào để tìm đúng endpoint?

\n
    \n
  1. Kiểm tra GET /endpoints cho danh sách đọc bằng máy
    2. \n
  2. Kiểm tra GET /help cho tài liệu API đầy đủ
    3. \n
  3. Duyệt GET /docs cho hệ thống tài liệu
    4. \n
  4. Sử dụng GET /openapi.json cho đặc tả OpenAPI 3.0
    5. \n
\n

Tôi có thể dùng GET thay vì POST không?

\n

Một số endpoint POST có phiên bản GET tương đương cho công cụ chỉ dùng URL:

\n\n

Kiểm tra GET /endpoints cho các biến thể GET khả dụng.

\n

Làm thế nào để xử lý lỗi?

\n

Tất cả lỗi trả về 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}

Xem Lỗi & Xử lý lỗi.

\n

Giới hạn body yêu cầu là bao nhiêu?

\n

10 MB. Cho payload lớn hơn (ví dụ tải tệp lên), sử dụng các endpoint multipart.

\n

API có hỗ trợ CORS không?

\n

Có. Tất cả endpoint trả về:

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

Có SDK không?

\n

Có:

\n\n

Xem Tổng quan API để biết chi tiết.

\n

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

\n

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

\n
curl ".../memory?limit=50&offset=100"

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

\n

Tôi có thể lọc bộ nhớ theo danh mục hoặc tag không?

\n

Có:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Làm thế nào để tìm kiếm bộ nhớ?

\n

Hai cách:

\n
    \n
  1. Tìm kiếm từ khóa FTS5: GET /memory/search?q=docker+swarm
    2. \n
  2. Tìm kiếm ngữ nghĩa: GET /memory/semantic-search?q=container+orchestration
    3. \n
\n

Xem Tìm kiếm FTS5 và Tìm kiếm ngữ nghĩa.

\n

Làm thế nào để cập nhật bộ nhớ?

\n

POST /memory với cùng category + key — bộ nhớ hiện có được cập nhật, không\ntrùng lặp.

\n
# Initial store\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Làm thế nào để xóa bộ nhớ?

\n
curl -X DELETE -H "Authorization: Bearer $KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

Tôi có thể xóa hàng loạt không?

\n

Có:

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

Bước tiếp theo

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