# API-FAQ

Häufige Fragen zur Synapse-API.

## Wie authentifiziere ich mich?

Zwei Methoden:

1. **Mind Key** (für Daten-Endpunkte): `Authorization: Bearer mk_...`
2. **JWT** (für Konto-Endpunkte): `Authorization: Bearer eyJ...`

Oder via Query-Parameter (60 req/min Limit): `?key=mk_...`

Siehe [Authentifizierung](/docs/getting-started/authentication).

## Was ist der Unterschied zwischen Mind Key und JWT?

- **Mind Key**: Tenant-scoped, läuft nie ab, für Memory-/Chat-/Tasks-Daten
- **JWT**: Nutzer-scoped, 7-Tage-Ablauf, für Konto-/Mind-Verwaltung

Siehe [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).

## Warum erhalte ich 401 Unauthorized?

Häufige Ursachen:

1. Fehlender `Authorization`-Header
2. Ungültiger Mind Key (prüfen, ob er mit `mk_` beginnt)
3. JWT verwendet, wo Mind Key erforderlich ist (oder umgekehrt)
4. Mind Key wurde widerrufen

**Lösung:** Token überprüfen. Siehe [Authentifizierung](/docs/getting-started/authentication).

## Warum erhalte ich 404 Not Found?

Du hast einen falschen Endpunkt-Pfad verwendet. Synapse hat nur die Pfade, die in
`GET /endpoints` gelistet sind.

**Lösung:** Rufe `GET /endpoints` auf, um alle gültigen Pfade zu sehen. Nicht
raten.

## Warum erhalte ich 429 Too Many Requests?

Du verwendest `?key=`-Query-Parameter-Auth, die auf 60/min begrenzt ist.

**Lösung:** Wechsle zum `Authorization: Bearer`-Header (kein Rate Limit).

Siehe [Rate Limits](/docs/api/rate-limits).

## Wie liste ich alle Endpunkte auf?

```bash
curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text
```

## Wie finde ich den richtigen Endpunkt?

1. Prüfe `GET /endpoints` für die maschinenlesbare Liste
2. Prüfe `GET /help` für die vollständige API-Doku
3. Durchsuche `GET /docs` für das Dokumentationssystem
4. Verwende `GET /openapi.json` für die OpenAPI-3.0-Spec

## Kann ich GET statt POST verwenden?

Einige POST-Endpunkte haben GET-Äquivalente für reine URL-Tools:

- `POST /memory` ↔ `GET /memory/store?content=...`
- `POST /mind/task` ↔ `GET /mind/task?title=...`
- `POST /chat/reply` ↔ `GET /chat/reply?content=...`

Prüfe `GET /endpoints` für verfügbare GET-Varianten.

## Wie behandle ich Fehler?

Alle Fehler liefern JSON:

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

Siehe [Errors & Fehlerbehandlung](/docs/api/errors).

## Wie hoch ist das Request-Body-Limit?

10 MB. Für größere Payloads (z. B. Datei-Uploads) verwende die Multipart-
Endpunkte.

## Unterstützt die API CORS?

Ja. Alle Endpunkte liefern:

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

## Gibt es ein SDK?

Ja:

- **Node.js**: `npm install synapse-memory-sdk`
- **MCP**: `npx -y synapse-mcp-api@latest`

Siehe [API-Übersicht](/docs/api/overview) für Details.

## Wie paginiere ich?

Verwende `?limit=` und `?offset=`:

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

Standard-Limit: 100. Max: 500.

## Kann ich Memories nach Kategorie oder Tag filtern?

Ja:

```bash
curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"
```

## Wie durchsuche ich Memories?

Zwei Wege:

1. **FTS5-Keyword-Suche**: `GET /memory/search?q=docker+swarm`
2. **Semantische Suche**: `GET /memory/semantic-search?q=container+orchestration`

Siehe [FTS5-Suche](/docs/concepts/fts5-search) und [Semantische Suche](/docs/concepts/semantic-search).

## Wie aktualisiere ich einen Memory?

POST `/memory` mit derselben `category` + `key` — der bestehende Memory wird
aktualisiert, nicht dupliziert.

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

## Wie lösche ich einen Memory?

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

## Kann ich Bulk-löschen?

Ja:

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

## Nächste Schritte

- [API-Übersicht](/docs/api/overview)
- [Errors & Fehlerbehandlung](/docs/api/errors)
- [Authentifizierung](/docs/getting-started/authentication)