# API FAQ

Common questions about the Synapse API.

## How do I authenticate?

Two methods:

1. **Mind Key** (for data endpoints): `Authorization: Bearer mk_...`
2. **JWT** (for account endpoints): `Authorization: Bearer eyJ...`

Or via query parameter (60 req/min limit): `?key=mk_...`

See [Authentication](/docs/getting-started/authentication).

## What's the difference between Mind Key and JWT?

- **Mind Key**: tenant-scoped, never expires, for memory/chat/tasks data
- **JWT**: user-scoped, 7-day expiry, for account/mind management

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

## Why am I getting 401 Unauthorized?

Common causes:

1. Missing `Authorization` header
2. Invalid Mind Key (verify it starts with `mk_`)
3. Using a JWT where a Mind Key is required (or vice versa)
4. Mind Key has been revoked

**Fix:** Verify your token. See [Authentication](/docs/getting-started/authentication).

## Why am I getting 404 Not Found?

You used a wrong endpoint path. Synapse only has the paths listed in
`GET /endpoints`.

**Fix:** Call `GET /endpoints` to see all valid paths. Don't guess.

## Why am I getting 429 Too Many Requests?

You're using `?key=` query parameter auth, which is rate-limited to 60/min.

**Fix:** Switch to `Authorization: Bearer` header (no rate limit).

See [Rate Limits](/docs/api/rate-limits).

## How do I list all endpoints?

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

## How do I find the right endpoint?

1. Check `GET /endpoints` for the machine-readable list
2. Check `GET /help` for full API docs
3. Browse `GET /docs` for the documentation system
4. Use `GET /openapi.json` for OpenAPI 3.0 spec

## Can I use GET instead of POST?

Some POST endpoints have GET equivalents for URL-only tools:

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

Check `GET /endpoints` for available GET variants.

## How do I handle errors?

All errors return JSON:

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

See [Errors & Error Handling](/docs/api/errors).

## What's the request body limit?

10 MB. For larger payloads (e.g. file uploads), use the multipart endpoints.

## Does the API support CORS?

Yes. All endpoints return:

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

## Is there an SDK?

Yes:

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

See [API Overview](/docs/api/overview) for details.

## How do I paginate?

Use `?limit=` and `?offset=`:

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

Default limit: 100. Max: 500.

## Can I filter memories by category or tag?

Yes:

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

## How do I search memories?

Two ways:

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

See [FTS5 Search](/docs/concepts/fts5-search) and [Semantic Search](/docs/concepts/semantic-search).

## How do I update a memory?

POST `/memory` with the same `category` + `key` — the existing memory is
updated, not duplicated.

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

## How do I delete a memory?

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

## Can I bulk delete?

Yes:

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

## Next Steps

- [API Overview](/docs/api/overview)
- [Errors & Error Handling](/docs/api/errors)
- [Authentication](/docs/getting-started/authentication)