# API 概要 & ベース URL

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

## ベース URL

```
https://synapse.schaefer.zone
```

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

## 認証

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

```
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints
```

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

```
?key=YOUR_MIND_KEY
```

詳しくは [Authentication](/docs/getting-started/authentication) を参照してください。

## エンドポイントグループ

| グループ | 認証 | 説明 |
|-------|------|-------------|
| Public | なし | ランディングページ、ヘルスチェック、OpenAPI、ドキュメント |
| Memory | Mind Key | CRUD、検索、同期、埋め込み |
| Chat | Mind Key / JWT | 人間とエージェント間の非同期メッセージング |
| Tasks | Mind Key | タスク管理 |
| Scripts | Mind Key / JWT | 永続スクリプトストア |
| Scheduler | Mind Key | Cron ジョブ + 変数 |
| Webhooks | Mind Key | イベント時の HTTP コールバック |
| Computers | Mind Key / JWT | リモートコンピュータ制御 |
| User/Minds | JWT | アカウント + mind 管理 |
| Sharing | JWT | ユーザー間の mind 共有 |
| Push | JWT | Web Push サブスクリプション |
| Tools | なし | 時刻、電卓、乱数（パブリックユーティリティ） |

## レスポンス形式

- **JSON**（デフォルト）：`{ "key": "value", ... }`
- **プレーンテキスト**：`/memory/recall` は LLM 向けに最適化されたテキストを返します
- **HTML**：`/`、`/docs`、`/human`、`/support`、`/playground`

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

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

```json
{ "id": "mem_001", "status": "stored" }
```

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

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

> [!NOTE]
> `docs` フィールドは、よくあるエラーに関するドキュメントへのリンクを提供します。

## HTTP ステータスコード

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

## 探索用エンドポイント

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

## レート制限

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

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

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)
```

## ページネーション

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

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

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

## CORS

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

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

## SDK & クライアント

- **Node.js SDK**：`npm install synapse-memory-sdk`（[リポジトリ](https://gitlab.com/schaefer-services/synapse-sdk-js)）
- **MCP Server**：`npx -y synapse-mcp-api@latest`（[リポジトリ](https://gitlab.com/schaefer-services/synapse-mcp)）
- **HTTP クライアント**：任意の HTTP ライブラリ（curl、fetch、axios など）

## 次のステップ

- [Memory API](/docs/api/memory) — 最も重要なエンドポイント
- [Chat API](/docs/api/chat) — 人間とエージェント間の非同期通信
- [Errors & Error Handling](/docs/api/errors)