{"title":"API FAQ","slug":"api-faq","category":"faq","summary":"일반적인 API 질문 — 인증, 속도 제한, 오류 처리, 엔드포인트 검색.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":336,"read_minutes":2,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# API FAQ\n\nSynapse API에 대한 일반적인 질문입니다.\n\n## 인증은 어떻게 합니까?\n\n두 가지 방법이 있습니다:\n\n1. **Mind Key** (데이터 엔드포인트용): `Authorization: Bearer mk_...`\n2. **JWT** (계정 엔드포인트용): `Authorization: Bearer eyJ...`\n\n또는 쿼리 파라미터로 (분당 60회 제한): `?key=mk_...`\n\n[Authentication](/docs/getting-started/authentication)을 참조하십시오.\n\n## Mind Key와 JWT의 차이는 무엇입니까?\n\n- **Mind Key**: 테넌트 범위, 만료 없음, memory/chat/tasks 데이터용\n- **JWT**: 사용자 범위, 7일 만료, 계정/마인드 관리용\n\n[Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)를 참조하십시오.\n\n## 왜 401 Unauthorized가 발생합니까?\n\n일반적인 원인:\n\n1. `Authorization` 헤더 누락\n2. 잘못된 Mind Key (`mk_`로 시작하는지 확인)\n3. Mind Key가 필요한 곳에 JWT 사용 (또는 그 반대)\n4. Mind Key가 취소됨\n\n**해결:** 토큰을 확인하십시오. [Authentication](/docs/getting-started/authentication)을 참조하십시오.\n\n## 왜 404 Not Found가 발생합니까?\n\n잘못된 엔드포인트 경로를 사용했습니다. Synapse에는 `GET /endpoints`에\n나열된 경로만 있습니다.\n\n**해결:** `GET /endpoints`를 호출하여 모든 유효한 경로를 확인하십시오. 추측하지 마십시오.\n\n## 왜 429 Too Many Requests가 발생합니까?\n\n속도 제한이 분당 60회인 `?key=` 쿼리 파라미터 인증을 사용 중입니다.\n\n**해결:** `Authorization: Bearer` 헤더로 전환하십시오 (속도 제한 없음).\n\n[속도 제한](/docs/api/rate-limits)을 참조하십시오.\n\n## 모든 엔드포인트를 어떻게 나열합니까?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## 올바른 엔드포인트를 어떻게 찾습니까?\n\n1. `GET /endpoints`에서 기계 판독 가능 목록 확인\n2. `GET /help`에서 전체 API 문서 확인\n3. `GET /docs`에서 문서 시스템 탐색\n4. `GET /openapi.json`에서 OpenAPI 3.0 사양 사용\n\n## POST 대신 GET을 사용할 수 있습니까?\n\n일부 POST 엔드포인트에는 URL 전용 도구를 위한 GET 동등물이 있습니다:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\n사용 가능한 GET 변형은 `GET /endpoints`에서 확인하십시오.\n\n## 오류는 어떻게 처리합니까?\n\n모든 오류는 JSON을 반환합니다:\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[오류 및 오류 처리](/docs/api/errors)를 참조하십시오.\n\n## 요청 본문 제한은 어떻게 됩니까?\n\n10 MB입니다. 더 큰 페이로드 (예: 파일 업로드)의 경우 multipart 엔드포인트를\n사용하십시오.\n\n## API는 CORS를 지원합니까?\n\n네. 모든 엔드포인트는 다음을 반환합니다:\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\n```\n\n## SDK가 있습니까?\n\n네:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\n자세한 내용은 [API 개요](/docs/api/overview)를 참조하십시오.\n\n## 페이지네이션은 어떻게 합니까?\n\n`?limit=` 및 `?offset=`을 사용하십시오:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\n기본 limit: 100. 최대: 500.\n\n## 카테고리나 태그로 메모리를 필터링할 수 있습니까?\n\n네:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## 메모리를 어떻게 검색합니까?\n\n두 가지 방법:\n\n1. **FTS5 키워드 검색**: `GET /memory/search?q=docker+swarm`\n2. **의미론적 검색**: `GET /memory/semantic-search?q=container+orchestration`\n\n[FTS5 검색](/docs/concepts/fts5-search) 및 [의미론적 검색](/docs/concepts/semantic-search)을 참조하십시오.\n\n## 메모리를 어떻게 업데이트합니까?\n\n동일한 `category` + `key`로 `/memory`를 POST하십시오 — 기존 메모리가\n업데이트되며 중복되지 않습니다.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## 메모리를 어떻게 삭제합니까?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## 대량 삭제할 수 있습니까?\n\n네:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## 다음 단계\n\n- [API 개요](/docs/api/overview)\n- [오류 및 오류 처리](/docs/api/errors)\n- [Authentication](/docs/getting-started/authentication)\n","content_html":"

API FAQ

\n

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

\n

인증은 어떻게 합니까?

\n

두 가지 방법이 있습니다:

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

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

\n

Authentication을 참조하십시오.

\n

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

\n\n

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

\n

왜 401 Unauthorized가 발생합니까?

\n

일반적인 원인:

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

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

\n

왜 404 Not Found가 발생합니까?

\n

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n

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

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

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

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

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

\n

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

\n\n

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

\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

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

\n

API는 CORS를 지원합니까?

\n

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

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

SDK가 있습니까?

\n

네:

\n\n

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

\n

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

\n

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

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

기본 limit: 100. 최대: 500.

\n

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

\n

네:

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

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

\n

두 가지 방법:

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

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

\n

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

\n

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

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

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

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

대량 삭제할 수 있습니까?

\n

네:

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

다음 단계

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}