API FAQ

Vanliga frågor om Synapse API.

Hur autentiserarar jag?

Två metoder:

1. Mind Key (för data-endpoints): Authorization: Bearer mk_...
2. JWT (för konto-endpoints): Authorization: Bearer eyJ...

Eller via queryparameter (60 req/min-gräns): ?key=mk_...

Se Autentisering.

Vad är skillnaden mellan Mind Key och JWT?

• Mind Key: klientomfattande, löper aldrig ut, för minnes-/chatt-/uppgiftsdata
• JWT: användaromfattande, 7 dagars giltighet, för konto-/mind-hantering

Se Mind Key vs JWT.

Varför får jag 401 Unauthorized?

Vanliga orsaker:

1. Saknad Authorization-header
2. Ogiltig Mind Key (verifiera att den börjar med mk_)
3. Användning av en JWT där en Mind Key krävs (eller tvärtom)
4. Mind Key har återkallats

Lösning: Verifiera din token. Se Autentisering.

Varför får jag 404 Not Found?

Ni använde en felaktig endpointsökväg. Synapse har endast de sökvägar som listas i GET /endpoints.

Lösning: Anropa GET /endpoints för att se alla giltiga sökvägar. Gissa inte.

Varför får jag 429 Too Many Requests?

Ni använder ?key=-queryparameter-autentisering, som är begränsad till 60/min.

Lösning: Byt till Authorization: Bearer-header (ingen hastighetsgräns).

Se Hastighetsgränser.

Hur listar jag alla endpoints?

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

Hur hittar jag rätt endpoint?

1. Kontrollera GET /endpoints för den maskinläsbara listan
2. Kontrollera GET /help för fullständig API-dokumentation
3. Bläddra i GET /docs för dokumentationssystemet
4. Använd GET /openapi.json för OpenAPI 3.0-specifikation

Kan jag använda GET istället för POST?

Vissa POST-endpoints har GET-motsvarigheter för URL-endast-verktyg:

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

Kontrollera GET /endpoints för tillgängliga GET-varianter.

Hur hanterar jag fel?

Alla fel returnerar JSON:

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

Se Fel & felhantering.

Vad är gränsen för begärans body?

10 MB. För större payloads (t.ex. filuppladdningar), använd multipart-endpoints.

Stöder API:et CORS?

Ja. Alla endpoints returnerar:

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

Finns det ett SDK?

Ja:

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

Se API-översikt för detaljer.

Hur paginerar jag?

Använd ?limit= och ?offset=:

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

Standardgräns: 100. Max: 500.

Kan jag filtrera minnen efter kategori eller tagg?

Ja:

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

Hur söker jag bland minnen?

På två sätt:

1. FTS5 nyckelordssökning: GET /memory/search?q=docker+swarm
2. Semantisk sökning: GET /memory/semantic-search?q=container+orchestration

Se FTS5-sökning och Semantisk sökning.

Hur uppdaterar jag ett minne?

POST /memory med samma category + key — det befintliga minnet uppdateras, inte dupliceras.

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

Hur tar jag bort ett minne?

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

Kan jag ta bort i bulk?

Ja:

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

Nästa steg

• API-översikt
• Fel & felhantering
• Autentisering