{"title":"ภาพรวม API และ Base URL","slug":"overview","category":"api","summary":"endpoint ทั้งหมดของ Synapse API, base URL, รูปแบบการยืนยันตัวตน และรูปแบบการตอบกลับในภาพรวม","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":489,"read_minutes":2,"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":"th","translated":true,"requested_lang":"th","content_markdown":"\n# ภาพรวม API และ Base URL\n\nSynapse API เป็น RESTful HTTP API ทุก endpoint ส่งกลับเป็น JSON (ยกเว้นในกรณีที่ระบุไว้เป็นอย่างอื่น) เอกสารหน้านี้ครอบคลุมสิ่งสำคัญที่คุณต้องรู้ก่อนเจาะลึก endpoint เฉพาะทาง\n\n## Base URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nพาธทั้งหมดในเอกสารนี้เป็นแบบ relative ต่อ base URL นี้ สำหรับ instance ที่ self-hosted ให้แทนที่ด้วย URL ของคุณเอง\n\n## การยืนยันตัวตน\n\nมีสองวิธี ทั้งคู่ส่งผ่าน `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # สำหรับ endpoint ข้อมูล\nAuthorization: Bearer YOUR_JWT # สำหรับ endpoint บัญชี\n```\n\nหรือผ่าน query parameter (จำกัดอัตรา 60 ครั้ง/นาที):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nดูรายละเอียดที่ [Authentication](/docs/getting-started/authentication)\n\n## กลุ่มของ Endpoint\n\n| กลุ่ม | Auth | คำอธิบาย |\n|-------|------|-------------|\n| Public | None | Landing page, health, OpenAPI, docs |\n| Memory | Mind Key | CRUD, search, sync, embeddings |\n| Chat | Mind Key / JWT | การส่งข้อความแบบ asynchronous ระหว่าง human และ agent |\n| Tasks | Mind Key | การจัดการ task |\n| Scripts | Mind Key / JWT | ที่เก็บ script แบบถาวร |\n| Scheduler | Mind Key | Cron jobs + variables |\n| Webhooks | Mind Key | HTTP callback บน event |\n| Computers | Mind Key / JWT | ควบคุม computer ระยะไกล |\n| User/Minds | JWT | บัญชี + การจัดการ mind |\n| Sharing | JWT | การแชร์ mind ระหว่างผู้ใช้ |\n| Push | JWT | Web Push subscriptions |\n| Tools | None | Time, calc, random (public utilities) |\n\n## รูปแบบการตอบกลับ\n\n- **JSON** (ค่าเริ่มต้น): `{ \"key\": \"value\", ... }`\n- **Plain text**: `/memory/recall` ส่งกลับเป็น text ที่ปรับให้เหมาะกับ LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Standard Response Envelope\n\nResponse สำเร็จส่งข้อมูลกลับมาโดยตรง:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nResponse ผิดพลาดใช้รูปแบบนี้:\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> ฟิลด์ `docs` เชื่อมโยงไปยังเอกสารที่เกี่ยวข้องสำหรับ error ทั่วไป\n\n## HTTP Status Codes\n\n| Code | ความหมาย |\n|------|---------|\n| 200 | Success (GET, PUT) |\n| 201 | Created (POST) |\n| 204 | No content (DELETE) |\n| 400 | Bad request (validation error) |\n| 401 | Unauthorized (missing/invalid token) |\n| 403 | Forbidden (wrong token type) |\n| 404 | Not found (path doesn't exist) |\n| 409 | Conflict (duplicate) |\n| 429 | Too many requests (rate limit) |\n| 500 | Server error |\n\n## Discoverability Endpoints\n\n| Endpoint | วัตถุประสงค์ |\n|----------|---------|\n| `GET /` | Landing page (LLM-optimized) |\n| `GET /endpoints` | รายการ machine-readable ของ endpoint ทั้งหมด |\n| `GET /endpoints?format=text` | รายการ endpoint ในรูปแบบ plain-text |\n| `GET /openapi.json` | OpenAPI 3.0 specification |\n| `GET /help` | เอกสาร API แบบเต็ม (HTML) |\n| `GET /help?format=json` | เอกสาร API ในรูปแบบ JSON |\n| `GET /docs` | ระบบเอกสาร (HTML) |\n| `GET /docs?format=json` | ดัชนีเอกสาร (JSON) |\n| `GET /docs?format=text&scope=all` | เอกสารทั้งหมดในรูปแบบ text block เดียว |\n| `GET /playground` | Interactive API playground |\n\n## Rate Limits\n\n| วิธี Auth | Limit |\n|-------------|-------|\n| Mind Key (header) | None |\n| Mind Key (?key=) | 60/min per IP |\n| JWT (header) | None |\n| Public endpoints | None |\n\nResponse ที่ถูกจำกัดอัตราจะมี:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Pagination\n\nEndpoint แบบ list รองรับ `?limit=` และ `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nLimit เริ่มต้น: 100 สูงสุด: 500\n\n## CORS\n\nทุก endpoint รองรับ CORS สำหรับ client ที่เป็น browser:\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## SDKs & Clients\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**: ไลบรารี HTTP ใดก็ได้ (curl, fetch, axios, etc.)\n\n## ขั้นตอนถัดไป\n\n- [Memory API](/docs/api/memory) — endpoint ที่สำคัญที่สุด\n- [Chat API](/docs/api/chat) — การสื่อสารระหว่าง human-agent แบบ asynchronous\n- [Errors & Error Handling](/docs/api/errors)\n","content_html":"

ภาพรวม API และ Base URL

\n

Synapse API เป็น RESTful HTTP API ทุก endpoint ส่งกลับเป็น JSON (ยกเว้นในกรณีที่ระบุไว้เป็นอย่างอื่น) เอกสารหน้านี้ครอบคลุมสิ่งสำคัญที่คุณต้องรู้ก่อนเจาะลึก endpoint เฉพาะทาง

\n

Base URL

\n
https://synapse.schaefer.zone

พาธทั้งหมดในเอกสารนี้เป็นแบบ relative ต่อ base URL นี้ สำหรับ instance ที่ self-hosted ให้แทนที่ด้วย URL ของคุณเอง

\n

การยืนยันตัวตน

\n

มีสองวิธี ทั้งคู่ส่งผ่าน Authorization header:

\n
Authorization: Bearer YOUR_MIND_KEY    # สำหรับ endpoint ข้อมูล\nAuthorization: Bearer YOUR_JWT          # สำหรับ endpoint บัญชี

หรือผ่าน query parameter (จำกัดอัตรา 60 ครั้ง/นาที):

\n
?key=YOUR_MIND_KEY

ดูรายละเอียดที่ Authentication

\n

กลุ่มของ 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
กลุ่มAuthคำอธิบาย
PublicNoneLanding page, health, OpenAPI, docs
MemoryMind KeyCRUD, search, sync, embeddings
ChatMind Key / JWTการส่งข้อความแบบ asynchronous ระหว่าง human และ agent
TasksMind Keyการจัดการ task
ScriptsMind Key / JWTที่เก็บ script แบบถาวร
SchedulerMind KeyCron jobs + variables
WebhooksMind KeyHTTP callback บน event
ComputersMind Key / JWTควบคุม computer ระยะไกล
User/MindsJWTบัญชี + การจัดการ mind
SharingJWTการแชร์ mind ระหว่างผู้ใช้
PushJWTWeb Push subscriptions
ToolsNoneTime, calc, random (public utilities)
\n

รูปแบบการตอบกลับ

\n\n

Standard Response Envelope

\n

Response สำเร็จส่งข้อมูลกลับมาโดยตรง:

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

Response ผิดพลาดใช้รูปแบบนี้:

\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}
ฟิลด์ `docs` เชื่อมโยงไปยังเอกสารที่เกี่ยวข้องสำหรับ error ทั่วไป

HTTP Status Codes

\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
Codeความหมาย
200Success (GET, PUT)
201Created (POST)
204No content (DELETE)
400Bad request (validation error)
401Unauthorized (missing/invalid token)
403Forbidden (wrong token type)
404Not found (path doesn't exist)
409Conflict (duplicate)
429Too many requests (rate limit)
500Server error
\n

Discoverability Endpoints

\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
Endpointวัตถุประสงค์
GET /Landing page (LLM-optimized)
GET /endpointsรายการ machine-readable ของ endpoint ทั้งหมด
GET /endpoints?format=textรายการ endpoint ในรูปแบบ plain-text
GET /openapi.jsonOpenAPI 3.0 specification
GET /helpเอกสาร API แบบเต็ม (HTML)
GET /help?format=jsonเอกสาร API ในรูปแบบ JSON
GET /docsระบบเอกสาร (HTML)
GET /docs?format=jsonดัชนีเอกสาร (JSON)
GET /docs?format=text&scope=allเอกสารทั้งหมดในรูปแบบ text block เดียว
GET /playgroundInteractive API playground
\n

Rate Limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
วิธี AuthLimit
Mind Key (header)None
Mind Key (?key=)60/min per IP
JWT (header)None
Public endpointsNone
\n

Response ที่ถูกจำกัดอัตราจะมี:

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

Pagination

\n

Endpoint แบบ list รองรับ ?limit= และ ?offset=:

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

Limit เริ่มต้น: 100 สูงสุด: 500

\n

CORS

\n

ทุก endpoint รองรับ CORS สำหรับ client ที่เป็น browser:

\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

SDKs & Clients

\n\n

ขั้นตอนถัดไป

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