Skip to main content

API FAQ

beginner 🤖 LLM対応 1 分 · 200 語 更新日: 2026-06-27 日本語

API に関するよくある質問 — 認証、レート制限、エラー処理、エンドポイント探索。

この記事を読む形式: 📄 プレーンテキスト ⚡ JSON 🤖 LLM形式
言語: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

API FAQ

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

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

2 つの方法があります。

  1. Mind Key（データエンドポイント用）：Authorization: Bearer mk_...
  2. JWT（アカウントエンドポイント用）：Authorization: Bearer eyJ...

またはクエリパラメータ経由（60 回/分の制限あり）：?key=mk_...

Authentication を参照。

Mind Key と JWT の違いは何ですか？

  • Mind Key：テナントスコープ、期限切れなし、メモリ/チャット/タスクデータ用
  • JWT：ユーザースコープ、7 日間の有効期限、アカウント/mind 管理用

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 が出るのはなぜですか？

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

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

Rate Limits を参照。

すべてのエンドポイントを一覧表示するには？

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

エラーはどう処理すればよいですか？

すべてのエラーは JSON を返します。

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

Errors & Error Handling を参照。

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

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

ページネーションはどうすればよいですか？

?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"

メモリを検索するには？

2 つの方法があります。

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

FTS5 Search と Semantic Search を参照。

メモリを更新するには？

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

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

次のステップ

← よくある質問 に戻る