# API-översikt & bas-URL

Synapse API är ett RESTful HTTP-API. Alla endpoints returnerar JSON (utom där
angivet). Den här sidan täcker det ni behöver veta innan ni dyker in i specifika
endpoints.

## Bas-URL

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

Alla sökvägar i denna dokumentation är relativa till denna bas-URL. För
självvärdda instanser, ersätt med er egen URL.

## Autentisering

Två metoder, båda skickade via `Authorization`-header:

```
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints
```

Eller via queryparameter (hastighetsbegränsad till 60/min):

```
?key=YOUR_MIND_KEY
```

Se [Autentisering](/docs/getting-started/authentication) för detaljer.

## Endpoint-grupper

| Grupp | Autentisering | Beskrivning |
|-------|------|-------------|
| Publik | Ingen | Landningssida, hälsa, OpenAPI, dokumentation |
| Memory | Mind Key | CRUD, sökning, synk, inbäddningar |
| Chat | Mind Key / JWT | Asynkrona meddelanden mellan människa och agent |
| Tasks | Mind Key | Uppgiftshantering |
| Scripts | Mind Key / JWT | Beständig skriptlagring |
| Scheduler | Mind Key | Cron-jobb + variabler |
| Webhooks | Mind Key | HTTP-återanrop vid händelser |
| Computers | Mind Key / JWT | Fjärrstyrning av datorer |
| User/Minds | JWT | Konto + mind-hantering |
| Sharing | JWT | Mind-delning mellan användare |
| Push | JWT | Web Push-prenumerationer |
| Tools | Ingen | Tid, kalkyl, slump (publika verktyg) |

## Svarsformat

- **JSON** (standard): `{ "key": "value", ... }`
- **Oformaterad text**: `/memory/recall` returnerar LLM-optimerad text
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Standard kuvert för svar

Lyckade svar returnerar datan direkt:

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

Felsvar använder detta format:

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

> [!NOTE]
> Fältet `docs` länkar till relevant dokumentation för vanliga fel.

## HTTP-statuskoder

| Kod | Betydelse |
|------|---------|
| 200 | Lyckades (GET, PUT) |
| 201 | Skapad (POST) |
| 204 | Inget innehåll (DELETE) |
| 400 | Felaktig begäran (valideringsfel) |
| 401 | Obehörig (saknas/ogiltig token) |
| 403 | Förbjuden (fel tokentyp) |
| 404 | Hittades inte (sökvägen finns inte) |
| 409 | Konflikt (dubblett) |
| 429 | För många begäranden (hastighetsgräns) |
| 500 | Serverfel |

## Upptäckbarhets-endpoints

| Endpoint | Syfte |
|----------|---------|
| `GET /` | Landningssida (LLM-optimerad) |
| `GET /endpoints` | Maskinläsbar lista över alla endpoints |
| `GET /endpoints?format=text` | Ofärmaterad endpoint-lista |
| `GET /openapi.json` | OpenAPI 3.0-specifikation |
| `GET /help` | Fullständig API-dokumentation (HTML) |
| `GET /help?format=json` | API-dokumentation som JSON |
| `GET /docs` | Dokumentationssystem (HTML) |
| `GET /docs?format=json` | Dokumentationsindex (JSON) |
| `GET /docs?format=text&scope=all` | All dokumentation som ett textblock |
| `GET /playground` | Interaktiv API-playground |

## Hastighetsgränser

| Autentiseringsmetod | Gräns |
|-------------|-------|
| Mind Key (header) | Ingen |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | Ingen |
| Publika endpoints | Ingen |

Hastighetsbegränsade svar inkluderar:

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

## Paginering

List-endpoints stöder `?limit=` och `?offset=`:

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

Standardgräns: 100. Maxgräns: 500.

## CORS

Alla endpoints stöder CORS för webbläsarbaserade klienter:

```
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:er & klienter

- **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-klient**: valfritt HTTP-bibliotek (curl, fetch, axios, etc.)

## Nästa steg

- [Memory API](/docs/api/memory) — de viktigaste endpoints
- [Chat API](/docs/api/chat) — asynkron kommunikation mellan människa och agent
- [Fel & felhantering](/docs/api/errors)