# API 개요 및 Base URL
SUMMARY: Synapse API의 모든 엔드포인트, Base URL, 인증 패턴, 응답 형식을 한눈에 살펴봅니다.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

API 개요 및 Base URL
Synapse API는 RESTful HTTP API입니다. 모든 엔드포인트는 (명시된 경우를
제외하고) JSON을 반환합니다. 이 페이지에서는 개별 엔드포인트를 살펴보기 전에
알아두어야 할 필수 사항을 다룹니다.
Base URL
[CODE BLOCK]
이 문서의 모든 경로는 위 Base URL을 기준으로 합니다. 자체 호스팅 인스턴스의
경우, 본인의 URL로 교체하십시오.
인증
두 가지 방법이 있으며, 모두  헤더로 전송합니다:
[CODE BLOCK]
또는 쿼리 파라미터로도 가능합니다 (분당 60회로 제한):
[CODE BLOCK]
자세한 내용은 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 (기본값): 
- 일반 텍스트: 은 LLM에 최적화된 텍스트를 반환
- HTML: , , , , 
표준 응답 봉투
성공 응답은 데이터를 직접 반환합니다:
[CODE BLOCK]
오류 응답은 다음 형식을 사용합니다:
[CODE BLOCK]
> [!NOTE]
>  필드는 일반적인 오류에 대한 관련 문서로 연결됩니다.
HTTP 상태 코드
| 코드 | 의미 |
|------|---------|
| 200 | 성공 (GET, PUT) |
| 201 | 생성됨 (POST) |
| 204 | 콘텐츠 없음 (DELETE) |
| 400 | 잘못된 요청 (검증 오류) |
| 401 | 인증되지 않음 (토큰 누락/잘못됨) |
| 403 | 금지됨 (잘못된 토큰 유형) |
| 404 | 찾을 수 없음 (경로가 존재하지 않음) |
| 409 | 충돌 (중복) |
| 429 | 요청이 너무 많음 (속도 제한) |
| 500 | 서버 오류 |
검색 가능 엔드포인트
| 엔드포인트 | 용도 |
|----------|---------|
|  | 랜딩 페이지 (LLM 최적화) |
|  | 모든 엔드포인트의 기계 판독 가능 목록 |
|  | 일반 텍스트 엔드포인트 목록 |
|  | OpenAPI 3.0 사양 |
|  | 전체 API 문서 (HTML) |
|  | JSON 형식의 API 문서 |
|  | 문서 시스템 (HTML) |
|  | 문서 인덱스 (JSON) |
|  | 모든 문서를 하나의 텍스트 블록으로 |
|  | 대화형 API 플레이그라운드 |
속도 제한
| 인증 방법 | 제한 |
|-------------|-------|
| Mind Key (헤더) | 없음 |
| Mind Key (?key=) | IP당 분당 60회 |
| JWT (헤더) | 없음 |
| 공용 엔드포인트 | 없음 |
속도 제한이 적용된 응답에는 다음이 포함됩니다:
[CODE BLOCK]
페이지네이션
목록 엔드포인트는  및 을 지원합니다:
[CODE BLOCK]
기본 limit: 100. 최대 limit: 500.
CORS
모든 엔드포인트는 브라우저 기반 클라이언트를 위한 CORS를 지원합니다:
[CODE BLOCK]
SDK 및 클라이언트
- Node.js SDK:  (저장소)
- MCP 서버:  (저장소)
- HTTP 클라이언트: 모든 HTTP 라이브러리 (curl, fetch, axios 등)
다음 단계
- Memory API — 가장 중요한 엔드포인트
- Chat API — 비동기 사람-에이전트 통신
- 오류 및 오류 처리