# API FAQ

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

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

2 つの方法があります。

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

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

[Authentication](/docs/getting-started/authentication) を参照。

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

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

[Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) を参照。

## 401 Unauthorized が出るのはなぜですか？

よくある原因：

1. `Authorization` ヘッダーの欠落
2. 無効な Mind Key（`mk_` で始まるか確認）
3. Mind Key が必要な場所で JWT を使用（またはその逆）
4. Mind Key が失効している

**対策：** トークンを確認してください。[Authentication](/docs/getting-started/authentication) を参照。

## 404 Not Found が出るのはなぜですか？

誤ったエンドポイントパスを使用しています。Synapse には `GET /endpoints` にリストされたパスのみが存在します。

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

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

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

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

[Rate Limits](/docs/api/rate-limits) を参照。

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

```bash
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 を返します。

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

[Errors & Error Handling](/docs/api/errors) を参照。

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

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](/docs/api/overview) を参照。

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

`?limit=` と `?offset=` を使用します。

```bash
curl ".../memory?limit=50&offset=100"
```

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

## カテゴリやタグでメモリをフィルタできますか？

はい。

```bash
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](/docs/concepts/fts5-search) と [Semantic Search](/docs/concepts/semantic-search) を参照。

## メモリを更新するには？

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

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

## メモリを削除するには？

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

## 一括削除はできますか？

はい。

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

## 次のステップ

- [API Overview](/docs/api/overview)
- [Errors & Error Handling](/docs/api/errors)
- [Authentication](/docs/getting-started/authentication)