API FAQ

Synapse API에 대한 일반적인 질문입니다.

인증은 어떻게 합니까?

두 가지 방법이 있습니다:

1. Mind Key (데이터 엔드포인트용): Authorization: Bearer mk_...
2. JWT (계정 엔드포인트용): Authorization: Bearer eyJ...

또는 쿼리 파라미터로 (분당 60회 제한): ?key=mk_...

Authentication을 참조하십시오.

Mind Key와 JWT의 차이는 무엇입니까?

• Mind Key: 테넌트 범위, 만료 없음, memory/chat/tasks 데이터용
• JWT: 사용자 범위, 7일 만료, 계정/마인드 관리용

Mind Key vs JWT를 참조하십시오.

왜 401 Unauthorized가 발생합니까?

일반적인 원인:

1. Authorization 헤더 누락
2. 잘못된 Mind Key (mk_로 시작하는지 확인)
3. Mind Key가 필요한 곳에 JWT 사용 (또는 그 반대)
4. Mind Key가 취소됨

해결: 토큰을 확인하십시오. Authentication을 참조하십시오.

왜 404 Not Found가 발생합니까?

잘못된 엔드포인트 경로를 사용했습니다. Synapse에는 GET /endpoints에 나열된 경로만 있습니다.

해결: GET /endpoints를 호출하여 모든 유효한 경로를 확인하십시오. 추측하지 마십시오.

왜 429 Too Many Requests가 발생합니까?

속도 제한이 분당 60회인 ?key= 쿼리 파라미터 인증을 사용 중입니다.

해결: Authorization: Bearer 헤더로 전환하십시오 (속도 제한 없음).

속도 제한을 참조하십시오.

모든 엔드포인트를 어떻게 나열합니까?

curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text

올바른 엔드포인트를 어떻게 찾습니까?

1. GET /endpoints에서 기계 판독 가능 목록 확인
2. GET /help에서 전체 API 문서 확인
3. GET /docs에서 문서 시스템 탐색
4. GET /openapi.json에서 OpenAPI 3.0 사양 사용

POST 대신 GET을 사용할 수 있습니까?

일부 POST 엔드포인트에는 URL 전용 도구를 위한 GET 동등물이 있습니다:

• POST /memory ↔ GET /memory/store?content=...
• POST /mind/task ↔ GET /mind/task?title=...
• POST /chat/reply ↔ GET /chat/reply?content=...

사용 가능한 GET 변형은 GET /endpoints에서 확인하십시오.

오류는 어떻게 처리합니까?

모든 오류는 JSON을 반환합니다:

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

오류 및 오류 처리를 참조하십시오.

요청 본문 제한은 어떻게 됩니까?

10 MB입니다. 더 큰 페이로드 (예: 파일 업로드)의 경우 multipart 엔드포인트를 사용하십시오.

API는 CORS를 지원합니까?

네. 모든 엔드포인트는 다음을 반환합니다:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT

SDK가 있습니까?

네:

• Node.js: npm install synapse-memory-sdk
• MCP: npx -y synapse-mcp-api@latest

자세한 내용은 API 개요를 참조하십시오.

페이지네이션은 어떻게 합니까?

?limit= 및 ?offset=을 사용하십시오:

curl ".../memory?limit=50&offset=100"

기본 limit: 100. 최대: 500.

카테고리나 태그로 메모리를 필터링할 수 있습니까?

네:

curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"

메모리를 어떻게 검색합니까?

두 가지 방법:

1. FTS5 키워드 검색: GET /memory/search?q=docker+swarm
2. 의미론적 검색: GET /memory/semantic-search?q=container+orchestration

FTS5 검색 및 의미론적 검색을 참조하십시오.

메모리를 어떻게 업데이트합니까?

동일한 category + key로 /memory를 POST하십시오 — 기존 메모리가 업데이트되며 중복되지 않습니다.

# Initial store
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Update (same key)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

메모리를 어떻게 삭제합니까?

curl -X DELETE -H "Authorization: Bearer $KEY" \
     https://synapse.schaefer.zone/memory/mem_001

대량 삭제할 수 있습니까?

네:

curl -X POST .../memory/bulk-delete \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

다음 단계

• API 개요
• 오류 및 오류 처리
• Authentication