# API FAQ

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

## 인증은 어떻게 합니까?

두 가지 방법이 있습니다:

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

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

[Authentication](/docs/getting-started/authentication)을 참조하십시오.

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

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

[Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)를 참조하십시오.

## 왜 401 Unauthorized가 발생합니까?

일반적인 원인:

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

**해결:** 토큰을 확인하십시오. [Authentication](/docs/getting-started/authentication)을 참조하십시오.

## 왜 404 Not Found가 발생합니까?

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

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

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

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

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

[속도 제한](/docs/api/rate-limits)을 참조하십시오.

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

```bash
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을 반환합니다:

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

[오류 및 오류 처리](/docs/api/errors)를 참조하십시오.

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

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 개요](/docs/api/overview)를 참조하십시오.

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

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

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

기본 limit: 100. 최대: 500.

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

네:

```bash
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 검색](/docs/concepts/fts5-search) 및 [의미론적 검색](/docs/concepts/semantic-search)을 참조하십시오.

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

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

```bash
# 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"}'
```

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

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

## 대량 삭제할 수 있습니까?

네:

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

## 다음 단계

- [API 개요](/docs/api/overview)
- [오류 및 오류 처리](/docs/api/errors)
- [Authentication](/docs/getting-started/authentication)