{"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":200,"read_minutes":1,"lang":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# API FAQ\n\nSynapse API に関するよくある質問です。\n\n## 認証はどうすればよいですか？\n\n2 つの方法があります。\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**：テナントスコープ、期限切れなし、メモリ/チャット/タスクデータ用\n- **JWT**：ユーザースコープ、7 日間の有効期限、アカウント/mind 管理用\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**対策：** `GET /endpoints` を呼び出して有効なパスをすべて確認してください。推測しないでください。\n\n## 429 Too Many Requests が出るのはなぜですか？\n\n`?key=` クエリパラメータ認証を使用しており、60 回/分にレート制限されています。\n\n**対策：** `Authorization: Bearer` ヘッダーに切り替えてください（レート制限なし）。\n\n[Rate Limits](/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 /endpoints` で利用可能な GET バリアントを確認してください。\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[Errors & Error Handling](/docs/api/errors) を参照。\n\n## リクエストボディの上限は？\n\n10 MB です。それ以上のペイロード（ファイルアップロードなど）には multipart エンドポイントを使用してください。\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 Overview](/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\n2 つの方法があります。\n\n1. **FTS5 キーワード検索**：`GET /memory/search?q=docker+swarm`\n2. **セマンティック検索**：`GET /memory/semantic-search?q=container+orchestration`\n\n[FTS5 Search](/docs/concepts/fts5-search) と [Semantic Search](/docs/concepts/semantic-search) を参照。\n\n## メモリを更新するには？\n\n同じ `category` + `key` で `POST /memory` を呼び出すと、既存メモリが重複ではなく更新されます。\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 Overview](/docs/api/overview)\n- [Errors & Error Handling](/docs/api/errors)\n- [Authentication](/docs/getting-started/authentication)\n","content_html":"

API FAQ

\n

Synapse API に関するよくある質問です。

\n

認証はどうすればよいですか？

\n

2 つの方法があります。

\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

対策： GET /endpoints を呼び出して有効なパスをすべて確認してください。推測しないでください。

\n

429 Too Many Requests が出るのはなぜですか？

\n

?key= クエリパラメータ認証を使用しており、60 回/分にレート制限されています。

\n

対策： Authorization: Bearer ヘッダーに切り替えてください（レート制限なし）。

\n

Rate Limits を参照。

\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 /endpoints で利用可能な GET バリアントを確認してください。

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

Errors & Error Handling を参照。

\n

リクエストボディの上限は？

\n

10 MB です。それ以上のペイロード（ファイルアップロードなど）には multipart エンドポイントを使用してください。

\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 Overview を参照。

\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

2 つの方法があります。

\n
    \n
  1. FTS5 キーワード検索：GET /memory/search?q=docker+swarm
    2. \n
  2. セマンティック検索：GET /memory/semantic-search?q=container+orchestration
    3. \n
\n

FTS5 Search と Semantic Search を参照。

\n

メモリを更新するには？

\n

同じ category + key で POST /memory を呼び出すと、既存メモリが重複ではなく更新されます。

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