# API 개요 및 Base URL

Synapse API는 RESTful HTTP API입니다. 모든 엔드포인트는 (명시된 경우를
제외하고) JSON을 반환합니다. 이 페이지에서는 개별 엔드포인트를 살펴보기 전에
알아두어야 할 필수 사항을 다룹니다.

## Base URL

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

이 문서의 모든 경로는 위 Base URL을 기준으로 합니다. 자체 호스팅 인스턴스의
경우, 본인의 URL로 교체하십시오.

## 인증

두 가지 방법이 있으며, 모두 `Authorization` 헤더로 전송합니다:

```
Authorization: Bearer YOUR_MIND_KEY    # 데이터 엔드포인트용
Authorization: Bearer YOUR_JWT          # 계정 엔드포인트용
```

또는 쿼리 파라미터로도 가능합니다 (분당 60회로 제한):

```
?key=YOUR_MIND_KEY
```

자세한 내용은 [Authentication](/docs/getting-started/authentication)을 참조하십시오.

## 엔드포인트 그룹

| 그룹 | 인증 | 설명 |
|-------|------|-------------|
| Public | 없음 | 랜딩 페이지, 상태 확인, OpenAPI, 문서 |
| Memory | Mind Key | CRUD, 검색, 동기화, 임베딩 |
| Chat | Mind Key / JWT | 사람과 에이전트 간 비동기 메시징 |
| Tasks | Mind Key | 작업 관리 |
| Scripts | Mind Key / JWT | 영구 스크립트 저장소 |
| Scheduler | Mind Key | Cron 작업 및 변수 |
| Webhooks | Mind Key | 이벤트 시 HTTP 콜백 |
| Computers | Mind Key / JWT | 원격 컴퓨터 제어 |
| User/Minds | JWT | 계정 및 마인드 관리 |
| Sharing | JWT | 사용자 간 마인드 공유 |
| Push | JWT | Web Push 구독 |
| Tools | 없음 | 시간, 계산, 무작위 (공용 유틸리티) |

## 응답 형식

- **JSON** (기본값): `{ "key": "value", ... }`
- **일반 텍스트**: `/memory/recall`은 LLM에 최적화된 텍스트를 반환
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## 표준 응답 봉투

성공 응답은 데이터를 직접 반환합니다:

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

오류 응답은 다음 형식을 사용합니다:

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

> [!NOTE]
> `docs` 필드는 일반적인 오류에 대한 관련 문서로 연결됩니다.

## HTTP 상태 코드

| 코드 | 의미 |
|------|---------|
| 200 | 성공 (GET, PUT) |
| 201 | 생성됨 (POST) |
| 204 | 콘텐츠 없음 (DELETE) |
| 400 | 잘못된 요청 (검증 오류) |
| 401 | 인증되지 않음 (토큰 누락/잘못됨) |
| 403 | 금지됨 (잘못된 토큰 유형) |
| 404 | 찾을 수 없음 (경로가 존재하지 않음) |
| 409 | 충돌 (중복) |
| 429 | 요청이 너무 많음 (속도 제한) |
| 500 | 서버 오류 |

## 검색 가능 엔드포인트

| 엔드포인트 | 용도 |
|----------|---------|
| `GET /` | 랜딩 페이지 (LLM 최적화) |
| `GET /endpoints` | 모든 엔드포인트의 기계 판독 가능 목록 |
| `GET /endpoints?format=text` | 일반 텍스트 엔드포인트 목록 |
| `GET /openapi.json` | OpenAPI 3.0 사양 |
| `GET /help` | 전체 API 문서 (HTML) |
| `GET /help?format=json` | JSON 형식의 API 문서 |
| `GET /docs` | 문서 시스템 (HTML) |
| `GET /docs?format=json` | 문서 인덱스 (JSON) |
| `GET /docs?format=text&scope=all` | 모든 문서를 하나의 텍스트 블록으로 |
| `GET /playground` | 대화형 API 플레이그라운드 |

## 속도 제한

| 인증 방법 | 제한 |
|-------------|-------|
| Mind Key (헤더) | 없음 |
| Mind Key (?key=) | IP당 분당 60회 |
| JWT (헤더) | 없음 |
| 공용 엔드포인트 | 없음 |

속도 제한이 적용된 응답에는 다음이 포함됩니다:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (429인 경우에만)
```

## 페이지네이션

목록 엔드포인트는 `?limit=` 및 `?offset=`을 지원합니다:

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

기본 limit: 100. 최대 limit: 500.

## CORS

모든 엔드포인트는 브라우저 기반 클라이언트를 위한 CORS를 지원합니다:

```
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 및 클라이언트

- **Node.js SDK**: `npm install synapse-memory-sdk` ([저장소](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP 서버**: `npx -y synapse-mcp-api@latest` ([저장소](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP 클라이언트**: 모든 HTTP 라이브러리 (curl, fetch, axios 등)

## 다음 단계

- [Memory API](/docs/api/memory) — 가장 중요한 엔드포인트
- [Chat API](/docs/api/chat) — 비동기 사람-에이전트 통신
- [오류 및 오류 처리](/docs/api/errors)