API 개요 및 Base URL

beginner 🤖 LLM 친화적 3 분 · 533 단어 업데이트: 2026-06-27 한국어

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

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을 참조하십시오.

엔드포인트 그룹

그룹	인증	설명
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

표준 응답 봉투

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

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

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

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

`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 (저장소)
MCP 서버: npx -y synapse-mcp-api@latest (저장소)
HTTP 클라이언트: 모든 HTTP 라이브러리 (curl, fetch, axios 등)

다음 단계

Memory API — 가장 중요한 엔드포인트
Chat API — 비동기 사람-에이전트 통신
오류 및 오류 처리