# API-FAQ

Veelgestelde vragen over de Synapse API.

## Hoe authenticeer ik?

Twee methoden:

1. **Mind Key** (voor data-eindpunten): `Authorization: Bearer mk_...`
2. **JWT** (voor account-eindpunten): `Authorization: Bearer eyJ...`

Of via queryparameter (limiet van 60 aanvragen/min): `?key=mk_...`

Zie [Authenticatie](/docs/getting-started/authentication).

## Wat is het verschil tussen Mind Key en JWT?

- **Mind Key**: tenant-scoped, vervalt nooit, voor memory/chat/tasks-data
- **JWT**: gebruiker-scoped, vervalt na 7 dagen, voor account/mind-beheer

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

## Waarom krijg ik 401 Unauthorized?

Veelvoorkomende oorzaken:

1. Ontbrekende `Authorization`-header
2. Ongeldige Mind Key (verifieer dat deze begint met `mk_`)
3. Een JWT gebruiken waar een Mind Key vereist is (of omgekeerd)
4. Mind Key is ingetrokken

**Oplossing:** Verifieer uw token. Zie [Authenticatie](/docs/getting-started/authentication).

## Waarom krijg ik 404 Not Found?

U heeft een verkeerd eindpuntpad gebruikt. Synapse heeft alleen de paden die in
`GET /endpoints` staan.

**Oplossing:** Roep `GET /endpoints` aan om alle geldige paden te zien. Raad niet.

## Waarom krijg ik 429 Too Many Requests?

U gebruikt `?key=`-queryparameter-auth, die is gelimiteerd tot 60/min.

**Oplossing:** Schakel over naar `Authorization: Bearer`-header (geen ratelimit).

Zie [Ratelimits](/docs/api/rate-limits).

## Hoe toon ik alle eindpunten?

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

## Hoe vind ik het juiste eindpunt?

1. Controleer `GET /endpoints` voor de machineleesbare lijst
2. Controleer `GET /help` voor volledige API-documentatie
3. Blader door `GET /docs` voor het documentatiesysteem
4. Gebruik `GET /openapi.json` voor de OpenAPI 3.0-specificatie

## Kan ik GET gebruiken in plaats van POST?

Sommige POST-eindpunten hebben GET-equivalenten voor URL-only tools:

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

Controleer `GET /endpoints` voor beschikbare GET-varianten.

## Hoe handel ik fouten af?

Alle fouten retourneren JSON:

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

Zie [Fouten & Foutafhandeling](/docs/api/errors).

## Wat is de limiet voor requestbody's?

10 MB. Voor grotere payloads (bijv. bestandsuploads), gebruik de multipart-eindpunten.

## Ondersteunt de API CORS?

Ja. Alle eindpunten retourneren:

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

## Is er een SDK?

Ja:

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

Zie [API-overzicht](/docs/api/overview) voor details.

## Hoe pagineer ik?

Gebruik `?limit=` en `?offset=`:

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

Standaardlimiet: 100. Maximum: 500.

## Kan ik herinneringen filteren op categorie of tag?

Ja:

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

## Hoe doorzoek ik herinneringen?

Twee manieren:

1. **FTS5 trefwoordzoekopdracht**: `GET /memory/search?q=docker+swarm`
2. **Semantisch zoeken**: `GET /memory/semantic-search?q=container+orchestration`

Zie [FTS5-zoekopdracht](/docs/concepts/fts5-search) en [Semantisch zoeken](/docs/concepts/semantic-search).

## Hoe werk ik een herinnering bij?

POST `/memory` met dezelfde `category` + `key` — de bestaande herinnering wordt
bijgewerkt, niet gedupliceerd.

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

## Hoe verwijder ik een herinnering?

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

## Kan ik in bulk verwijderen?

Ja:

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

## Volgende stappen

- [API-overzicht](/docs/api/overview)
- [Fouten & Foutafhandeling](/docs/api/errors)
- [Authenticatie](/docs/getting-started/authentication)