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.

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.

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.

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.

Hoe toon ik alle eindpunten?

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:

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

Zie Fouten & Foutafhandeling.

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 voor details.

Hoe pagineer ik?

Gebruik ?limit= en ?offset=:

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

Standaardlimiet: 100. Maximum: 500.

Kan ik herinneringen filteren op categorie of tag?

Ja:

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 en Semantisch zoeken.

Hoe werk ik een herinnering bij?

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

# 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?

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

Kan ik in bulk verwijderen?

Ja:

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

Volgende stappen

• API-overzicht
• Fouten & Foutafhandeling
• Authenticatie