{"title":"API 概要 & ベース URL","slug":"overview","category":"api","summary":"Synapse API の全エンドポイント、ベース URL、認証パターン、レスポンス形式を一覧でご紹介します。","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":374,"read_minutes":2,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# API 概要 & ベース URL\n\nSynapse API は RESTful な HTTP API です。特記のない限り、すべてのエンドポイントは JSON を返します。本ページでは、各エンドポイントの詳細に入る前に知っておくべき基本事項を説明します。\n\n## ベース URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\n本ドキュメント内のすべてのパスは、このベース URL に対する相対パスです。セルフホスト環境の場合は、ご自身の URL に置き換えてください。\n\n## 認証\n\n2 種類の方法があり、いずれも `Authorization` ヘッダーで送信します。\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # for data endpoints\nAuthorization: Bearer YOUR_JWT # for account endpoints\n```\n\nまたはクエリパラメータで送信することも可能です（60 回/分にレート制限されます）。\n\n```\n?key=YOUR_MIND_KEY\n```\n\n詳しくは [Authentication](/docs/getting-started/authentication) を参照してください。\n\n## エンドポイントグループ\n\n| グループ | 認証 | 説明 |\n|-------|------|-------------|\n| Public | なし | ランディングページ、ヘルスチェック、OpenAPI、ドキュメント |\n| Memory | Mind Key | CRUD、検索、同期、埋め込み |\n| Chat | Mind Key / JWT | 人間とエージェント間の非同期メッセージング |\n| Tasks | Mind Key | タスク管理 |\n| Scripts | Mind Key / JWT | 永続スクリプトストア |\n| Scheduler | Mind Key | Cron ジョブ + 変数 |\n| Webhooks | Mind Key | イベント時の HTTP コールバック |\n| Computers | Mind Key / JWT | リモートコンピュータ制御 |\n| User/Minds | JWT | アカウント + mind 管理 |\n| Sharing | JWT | ユーザー間の mind 共有 |\n| Push | JWT | Web Push サブスクリプション |\n| Tools | なし | 時刻、電卓、乱数（パブリックユーティリティ） |\n\n## レスポンス形式\n\n- **JSON**（デフォルト）：`{ \"key\": \"value\", ... }`\n- **プレーンテキスト**：`/memory/recall` は LLM 向けに最適化されたテキストを返します\n- **HTML**：`/`、`/docs`、`/human`、`/support`、`/playground`\n\n## 標準レスポンスエンベロープ\n\n成功時のレスポンスはデータを直接返します。\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nエラー時のレスポンスは以下の形式を使用します。\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> [!NOTE]\n> `docs` フィールドは、よくあるエラーに関するドキュメントへのリンクを提供します。\n\n## HTTP ステータスコード\n\n| コード | 意味 |\n|------|---------|\n| 200 | 成功（GET、PUT） |\n| 201 | 作成済み（POST） |\n| 204 | コンテンツなし（DELETE） |\n| 400 | 不正なリクエスト（バリデーションエラー） |\n| 401 | 認証エラー（トークン missing/invalid） |\n| 403 | 禁止（トークン種別の不一致） |\n| 404 | 見つからない（パスが存在しない） |\n| 409 | 競合（重複） |\n| 429 | リクエスト過多（レート制限） |\n| 500 | サーバーエラー |\n\n## 探索用エンドポイント\n\n| エンドポイント | 目的 |\n|----------|---------|\n| `GET /` | ランディングページ（LLM 向け最適化） |\n| `GET /endpoints` | すべてのエンドポイントの機械可読リスト |\n| `GET /endpoints?format=text` | プレーンテキスト形式のエンドポイントリスト |\n| `GET /openapi.json` | OpenAPI 3.0 仕様 |\n| `GET /help` | 完全な API ドキュメント（HTML） |\n| `GET /help?format=json` | JSON 形式の API ドキュメント |\n| `GET /docs` | ドキュメントシステム（HTML） |\n| `GET /docs?format=json` | ドキュメントインデックス（JSON） |\n| `GET /docs?format=text&scope=all` | すべてのドキュメントを 1 つのテキストブロックで |\n| `GET /playground` | インタラクティブな API プレイグラウンド |\n\n## レート制限\n\n| 認証方法 | 制限 |\n|-------------|-------|\n| Mind Key（ヘッダー） | なし |\n| Mind Key（?key=） | 60 回/分（IP ごと） |\n| JWT（ヘッダー） | なし |\n| パブリックエンドポイント | なし |\n\nレート制限対象のレスポンスには以下が含まれます。\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## ページネーション\n\nリストエンドポイントは `?limit=` と `?offset=` をサポートしています。\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nデフォルトの limit：100。最大 limit：500。\n\n## CORS\n\nすべてのエンドポイントはブラウザベースのクライアント向けに CORS をサポートしています。\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK & クライアント\n\n- **Node.js SDK**：`npm install synapse-memory-sdk`（[リポジトリ](https://gitlab.com/schaefer-services/synapse-sdk-js)）\n- **MCP Server**：`npx -y synapse-mcp-api@latest`（[リポジトリ](https://gitlab.com/schaefer-services/synapse-mcp)）\n- **HTTP クライアント**：任意の HTTP ライブラリ（curl、fetch、axios など）\n\n## 次のステップ\n\n- [Memory API](/docs/api/memory) — 最も重要なエンドポイント\n- [Chat API](/docs/api/chat) — 人間とエージェント間の非同期通信\n- [Errors & Error Handling](/docs/api/errors)\n","content_html":"

API 概要 & ベース URL

\n

Synapse API は RESTful な HTTP API です。特記のない限り、すべてのエンドポイントは JSON を返します。本ページでは、各エンドポイントの詳細に入る前に知っておくべき基本事項を説明します。

\n

ベース URL

\n
https://synapse.schaefer.zone

本ドキュメント内のすべてのパスは、このベース URL に対する相対パスです。セルフホスト環境の場合は、ご自身の URL に置き換えてください。

\n

認証

\n

2 種類の方法があり、いずれも Authorization ヘッダーで送信します。

\n
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints\nAuthorization: Bearer YOUR_JWT          # for account endpoints

またはクエリパラメータで送信することも可能です（60 回/分にレート制限されます）。

\n
?key=YOUR_MIND_KEY

詳しくは Authentication を参照してください。

\n

エンドポイントグループ

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
グループ認証説明
Publicなしランディングページ、ヘルスチェック、OpenAPI、ドキュメント
MemoryMind KeyCRUD、検索、同期、埋め込み
ChatMind Key / JWT人間とエージェント間の非同期メッセージング
TasksMind Keyタスク管理
ScriptsMind Key / JWT永続スクリプトストア
SchedulerMind KeyCron ジョブ + 変数
WebhooksMind Keyイベント時の HTTP コールバック
ComputersMind Key / JWTリモートコンピュータ制御
User/MindsJWTアカウント + mind 管理
SharingJWTユーザー間の mind 共有
PushJWTWeb Push サブスクリプション
Toolsなし時刻、電卓、乱数（パブリックユーティリティ）
\n

レスポンス形式

\n\n

標準レスポンスエンベロープ

\n

成功時のレスポンスはデータを直接返します。

\n
{ "id": "mem_001", "status": "stored" }

エラー時のレスポンスは以下の形式を使用します。

\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}
`docs` フィールドは、よくあるエラーに関するドキュメントへのリンクを提供します。

HTTP ステータスコード

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
コード意味
200成功（GET、PUT）
201作成済み（POST）
204コンテンツなし（DELETE）
400不正なリクエスト（バリデーションエラー）
401認証エラー（トークン missing/invalid）
403禁止（トークン種別の不一致）
404見つからない（パスが存在しない）
409競合（重複）
429リクエスト過多（レート制限）
500サーバーエラー
\n

探索用エンドポイント

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
エンドポイント目的
GET /ランディングページ（LLM 向け最適化）
GET /endpointsすべてのエンドポイントの機械可読リスト
GET /endpoints?format=textプレーンテキスト形式のエンドポイントリスト
GET /openapi.jsonOpenAPI 3.0 仕様
GET /help完全な API ドキュメント（HTML）
GET /help?format=jsonJSON 形式の API ドキュメント
GET /docsドキュメントシステム（HTML）
GET /docs?format=jsonドキュメントインデックス（JSON）
GET /docs?format=text&scope=allすべてのドキュメントを 1 つのテキストブロックで
GET /playgroundインタラクティブな API プレイグラウンド
\n

レート制限

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
認証方法制限
Mind Key（ヘッダー）なし
Mind Key（?key=）60 回/分（IP ごと）
JWT（ヘッダー）なし
パブリックエンドポイントなし
\n

レート制限対象のレスポンスには以下が含まれます。

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

ページネーション

\n

リストエンドポイントは ?limit= と ?offset= をサポートしています。

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

デフォルトの limit：100。最大 limit：500。

\n

CORS

\n

すべてのエンドポイントはブラウザベースのクライアント向けに CORS をサポートしています。

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

SDK & クライアント

\n\n

次のステップ

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