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.

¿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.

¿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.

¿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.

¿Cómo listo todos los endpoints?

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:

{
  "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.

¿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 para más detalles.

¿Cómo pagino?

Use ?limit= y ?offset=:

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

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

¿Puedo filtrar memorias por categoría o etiqueta?

Sí:

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 y Búsqueda semántica.

¿Cómo actualizo una memoria?

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

# 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?

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

¿Puedo eliminar en lote?

Sí:

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

Próximos pasos

• Resumen de la API
• Errores y manejo de errores
• Autenticación