# FAQ de la API

Preguntas comunes sobre la API de Synapse.

## ¿Cómo me autentico?

Dos métodos:

1. **Mind Key** (para endpoints de datos): `Authorization: Bearer mk_...`
2. **JWT** (para endpoints de cuenta): `Authorization: Bearer eyJ...`

O vía parámetro de consulta (límite de 60 req/min): `?key=mk_...`

Consulte [Autenticación](/docs/getting-started/authentication).

## ¿Cuál es la diferencia entre Mind Key y JWT?

- **Mind Key**: ámbito de tenant, nunca expira, para datos de memoria/chat/tareas
- **JWT**: ámbito de usuario, expira a los 7 días, para gestión de cuenta/mind

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

## ¿Por qué obtengo 401 Unauthorized?

Causas comunes:

1. Falta la cabecera `Authorization`
2. Mind Key inválido (verifique que empieza por `mk_`)
3. Uso de un JWT donde se requiere un Mind Key (o viceversa)
4. El Mind Key ha sido revocado

**Solución:** Verifique su token. Consulte [Autenticación](/docs/getting-started/authentication).

## ¿Por qué obtengo 404 Not Found?

Usó una ruta de endpoint incorrecta. Synapse solo tiene las rutas listadas en
`GET /endpoints`.

**Solución:** Llame a `GET /endpoints` para ver todas las rutas válidas. No
adivine.

## ¿Por qué obtengo 429 Too Many Requests?

Está usando autenticación por parámetro de consulta `?key=`, que está limitada a
60/min.

**Solución:** Cambie a la cabecera `Authorization: Bearer` (sin límite de
frecuencia).

Consulte [Límites de frecuencia](/docs/api/rate-limits).

## ¿Cómo listo todos los endpoints?

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

## ¿Cómo encuentro el endpoint correcto?

1. Consulte `GET /endpoints` para la lista legible por máquina
2. Consulte `GET /help` para la documentación completa de la API
3. Explore `GET /docs` para el sistema de documentación
4. Use `GET /openapi.json` para la especificación OpenAPI 3.0

## ¿Puedo usar GET en lugar de POST?

Algunos endpoints POST tienen equivalentes GET para herramientas que solo usan
URL:

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

Consulte `GET /endpoints` para ver las variantes GET disponibles.

## ¿Cómo manejo los errores?

Todos los errores devuelven JSON:

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

Consulte [Errores y manejo de errores](/docs/api/errors).

## ¿Cuál es el límite del cuerpo de la solicitud?

10 MB. Para payloads más grandes (p. ej. subida de archivos), use los endpoints
multipart.

## ¿La API admite CORS?

Sí. Todos los endpoints devuelven:

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

## ¿Hay un SDK?

Sí:

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

Consulte [Resumen de la API](/docs/api/overview) para más detalles.

## ¿Cómo pagino?

Use `?limit=` y `?offset=`:

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

Límite predeterminado: 100. Máximo: 500.

## ¿Puedo filtrar memorias por categoría o etiqueta?

Sí:

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

## ¿Cómo busco memorias?

De dos formas:

1. **Búsqueda por palabra clave FTS5**: `GET /memory/search?q=docker+swarm`
2. **Búsqueda semántica**: `GET /memory/semantic-search?q=container+orchestration`

Consulte [Búsqueda FTS5](/docs/concepts/fts5-search) y [Búsqueda semántica](/docs/concepts/semantic-search).

## ¿Cómo actualizo una memoria?

POST `/memory` con la misma `category` + `key` — la memoria existente se
actualiza, no se duplica.

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

## ¿Cómo elimino una memoria?

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

## ¿Puedo eliminar en lote?

Sí:

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

## Próximos pasos

- [Resumen de la API](/docs/api/overview)
- [Errores y manejo de errores](/docs/api/errors)
- [Autenticación](/docs/getting-started/authentication)