# API-overzicht & Base URL

De Synapse API is een RESTful HTTP-API. Alle eindpunten retourneren JSON (behalve waar
vermeld). Deze pagina behandelt de essentiële zaken voordat u naar specifieke
eindpunten duikt.

## Base URL

```
https://synapse.schaefer.zone
```

Alle paden in deze documentatie zijn relatief ten opzichte van deze base URL. Voor
self-hosted instanties vervangt u dit door uw eigen URL.

## Authenticatie

Twee methoden, beide via de `Authorization`-header:

```
Authorization: Bearer YOUR_MIND_KEY    # voor data-eindpunten
Authorization: Bearer YOUR_JWT          # voor account-eindpunten
```

Of via queryparameter (ratelimited tot 60/min):

```
?key=YOUR_MIND_KEY
```

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

## Eindpuntgroepen

| Groep | Auth | Beschrijving |
|-------|------|--------------|
| Public | Geen | Landingspagina, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, zoeken, synchroniseren, embeddings |
| Chat | Mind Key / JWT | Asynchrone berichtenuitwisseling tussen mens en agent |
| Tasks | Mind Key | Taakbeheer |
| Scripts | Mind Key / JWT | Permanente script-opslag |
| Scheduler | Mind Key | Cron-jobs + variabelen |
| Webhooks | Mind Key | HTTP-callbacks bij gebeurtenissen |
| Computers | Mind Key / JWT | Bediening van computers op afstand |
| User/Minds | JWT | Account + mind-beheer |
| Sharing | JWT | Mind delen tussen gebruikers |
| Push | JWT | Web Push-abonnementen |
| Tools | Geen | Tijd, calc, random (openbare hulpmiddelen) |

## Responsformaten

- **JSON** (standaard): `{ "key": "value", ... }`
- **Platte tekst**: `/memory/recall` retourneert op LLM geoptimaliseerde tekst
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Standaard respons-envelope

Succesresponsen retourneren de data direct:

```json
{ "id": "mem_001", "status": "stored" }
```

Foutresponsen gebruiken dit formaat:

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

> [!NOTE]
> Het `docs`-veld verwijst naar relevante documentatie voor veelvoorkomende fouten.

## HTTP-statuscodes

| Code | Betekenis |
|------|-----------|
| 200 | Succes (GET, PUT) |
| 201 | Aangemaakt (POST) |
| 204 | Geen inhoud (DELETE) |
| 400 | Onjuist verzoek (validatiefout) |
| 401 | Niet-geautoriseerd (ontbrekend/ongeldig token) |
| 403 | Verboden (verkeerd tokentype) |
| 404 | Niet gevonden (pad bestaat niet) |
| 409 | Conflict (dubbeling) |
| 429 | Te veel verzoeken (ratelimit) |
| 500 | Serverfout |

## Ontdekkings-eindpunten

| Eindpunt | Doel |
|----------|------|
| `GET /` | Landingspagina (op LLM geoptimaliseerd) |
| `GET /endpoints` | Machineleesbare lijst van alle eindpunten |
| `GET /endpoints?format=text` | Plattetekst eindpuntlijst |
| `GET /openapi.json` | OpenAPI 3.0-specificatie |
| `GET /help` | Volledige API-documentatie (HTML) |
| `GET /help?format=json` | API-documentatie als JSON |
| `GET /docs` | Documentatiesysteem (HTML) |
| `GET /docs?format=json` | Documentatie-index (JSON) |
| `GET /docs?format=text&scope=all` | Alle documentatie als één tekstblok |
| `GET /playground` | Interactieve API-playground |

## Ratelimits

| Auth-methode | Limiet |
|--------------|--------|
| Mind Key (header) | Geen |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | Geen |
| Openbare eindpunten | Geen |

Ratelimited responsen bevatten:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)
```

## Paginering

Lijst-eindpunten ondersteunen `?limit=` en `?offset=`:

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

Standaardlimiet: 100. Maximale limiet: 500.

## CORS

Alle eindpunten ondersteunen CORS voor browser-gebaseerde clients:

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

## SDK's & Clients

- **Node.js SDK**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP-client**: elke HTTP-bibliotheek (curl, fetch, axios, enz.)

## Volgende stappen

- [Memory API](/docs/api/memory) — de belangrijkste eindpunten
- [Chat API](/docs/api/chat) — asynchrone communicatie tussen mens en agent
- [Fouten & Foutafhandeling](/docs/api/errors)