{"title":"API 개요 및 Base URL","slug":"overview","category":"api","summary":"Synapse API의 모든 엔드포인트, Base URL, 인증 패턴, 응답 형식을 한눈에 살펴봅니다.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":533,"read_minutes":3,"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":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# API 개요 및 Base URL\n\nSynapse API는 RESTful HTTP API입니다. 모든 엔드포인트는 (명시된 경우를\n제외하고) JSON을 반환합니다. 이 페이지에서는 개별 엔드포인트를 살펴보기 전에\n알아두어야 할 필수 사항을 다룹니다.\n\n## Base URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\n이 문서의 모든 경로는 위 Base URL을 기준으로 합니다. 자체 호스팅 인스턴스의\n경우, 본인의 URL로 교체하십시오.\n\n## 인증\n\n두 가지 방법이 있으며, 모두 `Authorization` 헤더로 전송합니다:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # 데이터 엔드포인트용\nAuthorization: Bearer YOUR_JWT # 계정 엔드포인트용\n```\n\n또는 쿼리 파라미터로도 가능합니다 (분당 60회로 제한):\n\n```\n?key=YOUR_MIND_KEY\n```\n\n자세한 내용은 [Authentication](/docs/getting-started/authentication)을 참조하십시오.\n\n## 엔드포인트 그룹\n\n| 그룹 | 인증 | 설명 |\n|-------|------|-------------|\n| Public | 없음 | 랜딩 페이지, 상태 확인, OpenAPI, 문서 |\n| Memory | Mind Key | CRUD, 검색, 동기화, 임베딩 |\n| Chat | Mind Key / JWT | 사람과 에이전트 간 비동기 메시징 |\n| Tasks | Mind Key | 작업 관리 |\n| Scripts | Mind Key / JWT | 영구 스크립트 저장소 |\n| Scheduler | Mind Key | Cron 작업 및 변수 |\n| Webhooks | Mind Key | 이벤트 시 HTTP 콜백 |\n| Computers | Mind Key / JWT | 원격 컴퓨터 제어 |\n| User/Minds | JWT | 계정 및 마인드 관리 |\n| Sharing | JWT | 사용자 간 마인드 공유 |\n| Push | JWT | Web Push 구독 |\n| Tools | 없음 | 시간, 계산, 무작위 (공용 유틸리티) |\n\n## 응답 형식\n\n- **JSON** (기본값): `{ \"key\": \"value\", ... }`\n- **일반 텍스트**: `/memory/recall`은 LLM에 최적화된 텍스트를 반환\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## 표준 응답 봉투\n\n성공 응답은 데이터를 직접 반환합니다:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\n오류 응답은 다음 형식을 사용합니다:\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` 필드는 일반적인 오류에 대한 관련 문서로 연결됩니다.\n\n## HTTP 상태 코드\n\n| 코드 | 의미 |\n|------|---------|\n| 200 | 성공 (GET, PUT) |\n| 201 | 생성됨 (POST) |\n| 204 | 콘텐츠 없음 (DELETE) |\n| 400 | 잘못된 요청 (검증 오류) |\n| 401 | 인증되지 않음 (토큰 누락/잘못됨) |\n| 403 | 금지됨 (잘못된 토큰 유형) |\n| 404 | 찾을 수 없음 (경로가 존재하지 않음) |\n| 409 | 충돌 (중복) |\n| 429 | 요청이 너무 많음 (속도 제한) |\n| 500 | 서버 오류 |\n\n## 검색 가능 엔드포인트\n\n| 엔드포인트 | 용도 |\n|----------|---------|\n| `GET /` | 랜딩 페이지 (LLM 최적화) |\n| `GET /endpoints` | 모든 엔드포인트의 기계 판독 가능 목록 |\n| `GET /endpoints?format=text` | 일반 텍스트 엔드포인트 목록 |\n| `GET /openapi.json` | OpenAPI 3.0 사양 |\n| `GET /help` | 전체 API 문서 (HTML) |\n| `GET /help?format=json` | JSON 형식의 API 문서 |\n| `GET /docs` | 문서 시스템 (HTML) |\n| `GET /docs?format=json` | 문서 인덱스 (JSON) |\n| `GET /docs?format=text&scope=all` | 모든 문서를 하나의 텍스트 블록으로 |\n| `GET /playground` | 대화형 API 플레이그라운드 |\n\n## 속도 제한\n\n| 인증 방법 | 제한 |\n|-------------|-------|\n| Mind Key (헤더) | 없음 |\n| Mind Key (?key=) | IP당 분당 60회 |\n| JWT (헤더) | 없음 |\n| 공용 엔드포인트 | 없음 |\n\n속도 제한이 적용된 응답에는 다음이 포함됩니다:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (429인 경우에만)\n```\n\n## 페이지네이션\n\n목록 엔드포인트는 `?limit=` 및 `?offset=`을 지원합니다:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\n기본 limit: 100. 최대 limit: 500.\n\n## CORS\n\n모든 엔드포인트는 브라우저 기반 클라이언트를 위한 CORS를 지원합니다:\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## SDK 및 클라이언트\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([저장소](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP 서버**: `npx -y synapse-mcp-api@latest` ([저장소](https://gitlab.com/schaefer-services/synapse-mcp))\n- **HTTP 클라이언트**: 모든 HTTP 라이브러리 (curl, fetch, axios 등)\n\n## 다음 단계\n\n- [Memory API](/docs/api/memory) — 가장 중요한 엔드포인트\n- [Chat API](/docs/api/chat) — 비동기 사람-에이전트 통신\n- [오류 및 오류 처리](/docs/api/errors)\n","content_html":"

API 개요 및 Base URL

\n

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

\n

Base URL

\n
https://synapse.schaefer.zone

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

\n

인증

\n

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

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

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

\n
?key=YOUR_MIND_KEY

자세한 내용은 Authentication을 참조하십시오.

\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\n
그룹인증설명
Public없음랜딩 페이지, 상태 확인, OpenAPI, 문서
MemoryMind KeyCRUD, 검색, 동기화, 임베딩
ChatMind Key / JWT사람과 에이전트 간 비동기 메시징
TasksMind Key작업 관리
ScriptsMind Key / JWT영구 스크립트 저장소
SchedulerMind KeyCron 작업 및 변수
WebhooksMind Key이벤트 시 HTTP 콜백
ComputersMind Key / JWT원격 컴퓨터 제어
User/MindsJWT계정 및 마인드 관리
SharingJWT사용자 간 마인드 공유
PushJWTWeb Push 구독
Tools없음시간, 계산, 무작위 (공용 유틸리티)
\n

응답 형식

\n\n

표준 응답 봉투

\n

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

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

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

\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` 필드는 일반적인 오류에 대한 관련 문서로 연결됩니다.

HTTP 상태 코드

\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
코드의미
200성공 (GET, PUT)
201생성됨 (POST)
204콘텐츠 없음 (DELETE)
400잘못된 요청 (검증 오류)
401인증되지 않음 (토큰 누락/잘못됨)
403금지됨 (잘못된 토큰 유형)
404찾을 수 없음 (경로가 존재하지 않음)
409충돌 (중복)
429요청이 너무 많음 (속도 제한)
500서버 오류
\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
엔드포인트용도
GET /랜딩 페이지 (LLM 최적화)
GET /endpoints모든 엔드포인트의 기계 판독 가능 목록
GET /endpoints?format=text일반 텍스트 엔드포인트 목록
GET /openapi.jsonOpenAPI 3.0 사양
GET /help전체 API 문서 (HTML)
GET /help?format=jsonJSON 형식의 API 문서
GET /docs문서 시스템 (HTML)
GET /docs?format=json문서 인덱스 (JSON)
GET /docs?format=text&scope=all모든 문서를 하나의 텍스트 블록으로
GET /playground대화형 API 플레이그라운드
\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
인증 방법제한
Mind Key (헤더)없음
Mind Key (?key=)IP당 분당 60회
JWT (헤더)없음
공용 엔드포인트없음
\n

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (429인 경우에만)

페이지네이션

\n

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

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

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

\n

CORS

\n

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

\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

SDK 및 클라이언트

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