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

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

## Base URL

```
https://synapse.schaefer.zone
```

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

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

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

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

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

```
?key=YOUR_MIND_KEY
```

ดูรายละเอียดที่ [Authentication](/docs/getting-started/authentication)

## กลุ่มของ Endpoint

| กลุ่ม | Auth | คำอธิบาย |
|-------|------|-------------|
| Public | None | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, search, sync, embeddings |
| Chat | Mind Key / JWT | การส่งข้อความแบบ asynchronous ระหว่าง human และ agent |
| Tasks | Mind Key | การจัดการ task |
| Scripts | Mind Key / JWT | ที่เก็บ script แบบถาวร |
| Scheduler | Mind Key | Cron jobs + variables |
| Webhooks | Mind Key | HTTP callback บน event |
| Computers | Mind Key / JWT | ควบคุม computer ระยะไกล |
| User/Minds | JWT | บัญชี + การจัดการ mind |
| Sharing | JWT | การแชร์ mind ระหว่างผู้ใช้ |
| Push | JWT | Web Push subscriptions |
| Tools | None | Time, calc, random (public utilities) |

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

- **JSON** (ค่าเริ่มต้น): `{ "key": "value", ... }`
- **Plain text**: `/memory/recall` ส่งกลับเป็น text ที่ปรับให้เหมาะกับ LLM
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Standard Response Envelope

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

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

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

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

> [!NOTE]
> ฟิลด์ `docs` เชื่อมโยงไปยังเอกสารที่เกี่ยวข้องสำหรับ error ทั่วไป

## HTTP Status Codes

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

## Discoverability Endpoints

| Endpoint | วัตถุประสงค์ |
|----------|---------|
| `GET /` | Landing page (LLM-optimized) |
| `GET /endpoints` | รายการ machine-readable ของ endpoint ทั้งหมด |
| `GET /endpoints?format=text` | รายการ endpoint ในรูปแบบ plain-text |
| `GET /openapi.json` | OpenAPI 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 /playground` | Interactive API playground |

## Rate Limits

| วิธี Auth | Limit |
|-------------|-------|
| Mind Key (header) | None |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | None |
| Public endpoints | None |

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

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)
```

## Pagination

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

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

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

## CORS

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

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

## SDKs & Clients

- **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**: ไลบรารี HTTP ใดก็ได้ (curl, fetch, axios, etc.)

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

- [Memory API](/docs/api/memory) — endpoint ที่สำคัญที่สุด
- [Chat API](/docs/api/chat) — การสื่อสารระหว่าง human-agent แบบ asynchronous
- [Errors & Error Handling](/docs/api/errors)