{"title":"FAQ de la API","slug":"api-faq","category":"faq","summary":"Preguntas comunes sobre la API — autenticación, límites de frecuencia, manejo de errores, descubrimiento de endpoints.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":424,"read_minutes":2,"lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# FAQ de la API\n\nPreguntas comunes sobre la API de Synapse.\n\n## ¿Cómo me autentico?\n\nDos métodos:\n\n1. **Mind Key** (para endpoints de datos): `Authorization: Bearer mk_...`\n2. **JWT** (para endpoints de cuenta): `Authorization: Bearer eyJ...`\n\nO vía parámetro de consulta (límite de 60 req/min): `?key=mk_...`\n\nConsulte [Autenticación](/docs/getting-started/authentication).\n\n## ¿Cuál es la diferencia entre Mind Key y JWT?\n\n- **Mind Key**: ámbito de tenant, nunca expira, para datos de memoria/chat/tareas\n- **JWT**: ámbito de usuario, expira a los 7 días, para gestión de cuenta/mind\n\nConsulte [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## ¿Por qué obtengo 401 Unauthorized?\n\nCausas comunes:\n\n1. Falta la cabecera `Authorization`\n2. Mind Key inválido (verifique que empieza por `mk_`)\n3. Uso de un JWT donde se requiere un Mind Key (o viceversa)\n4. El Mind Key ha sido revocado\n\n**Solución:** Verifique su token. Consulte [Autenticación](/docs/getting-started/authentication).\n\n## ¿Por qué obtengo 404 Not Found?\n\nUsó una ruta de endpoint incorrecta. Synapse solo tiene las rutas listadas en\n`GET /endpoints`.\n\n**Solución:** Llame a `GET /endpoints` para ver todas las rutas válidas. No\nadivine.\n\n## ¿Por qué obtengo 429 Too Many Requests?\n\nEstá usando autenticación por parámetro de consulta `?key=`, que está limitada a\n60/min.\n\n**Solución:** Cambie a la cabecera `Authorization: Bearer` (sin límite de\nfrecuencia).\n\nConsulte [Límites de frecuencia](/docs/api/rate-limits).\n\n## ¿Cómo listo todos los endpoints?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## ¿Cómo encuentro el endpoint correcto?\n\n1. Consulte `GET /endpoints` para la lista legible por máquina\n2. Consulte `GET /help` para la documentación completa de la API\n3. Explore `GET /docs` para el sistema de documentación\n4. Use `GET /openapi.json` para la especificación OpenAPI 3.0\n\n## ¿Puedo usar GET en lugar de POST?\n\nAlgunos endpoints POST tienen equivalentes GET para herramientas que solo usan\nURL:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nConsulte `GET /endpoints` para ver las variantes GET disponibles.\n\n## ¿Cómo manejo los errores?\n\nTodos los errores devuelven JSON:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\nConsulte [Errores y manejo de errores](/docs/api/errors).\n\n## ¿Cuál es el límite del cuerpo de la solicitud?\n\n10 MB. Para payloads más grandes (p. ej. subida de archivos), use los endpoints\nmultipart.\n\n## ¿La API admite CORS?\n\nSí. Todos los endpoints devuelven:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## ¿Hay un SDK?\n\nSí:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nConsulte [Resumen de la API](/docs/api/overview) para más detalles.\n\n## ¿Cómo pagino?\n\nUse `?limit=` y `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nLímite predeterminado: 100. Máximo: 500.\n\n## ¿Puedo filtrar memorias por categoría o etiqueta?\n\nSí:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## ¿Cómo busco memorias?\n\nDe dos formas:\n\n1. **Búsqueda por palabra clave FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Búsqueda semántica**: `GET /memory/semantic-search?q=container+orchestration`\n\nConsulte [Búsqueda FTS5](/docs/concepts/fts5-search) y [Búsqueda semántica](/docs/concepts/semantic-search).\n\n## ¿Cómo actualizo una memoria?\n\nPOST `/memory` con la misma `category` + `key` — la memoria existente se\nactualiza, no se duplica.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## ¿Cómo elimino una memoria?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## ¿Puedo eliminar en lote?\n\nSí:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Próximos pasos\n\n- [Resumen de la API](/docs/api/overview)\n- [Errores y manejo de errores](/docs/api/errors)\n- [Autenticación](/docs/getting-started/authentication)\n","content_html":"

FAQ de la API

\n

Preguntas comunes sobre la API de Synapse.

\n

¿Cómo me autentico?

\n

Dos métodos:

\n
    \n
  1. Mind Key (para endpoints de datos): Authorization: Bearer mk_...
    2. \n
  2. JWT (para endpoints de cuenta): Authorization: Bearer eyJ...
    3. \n
\n

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

\n

Consulte Autenticación.

\n

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

\n\n

Consulte Mind Key vs JWT.

\n

¿Por qué obtengo 401 Unauthorized?

\n

Causas comunes:

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

Solución: Verifique su token. Consulte Autenticación.

\n

¿Por qué obtengo 404 Not Found?

\n

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

\n

Solución: Llame a GET /endpoints para ver todas las rutas válidas. No\nadivine.

\n

¿Por qué obtengo 429 Too Many Requests?

\n

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

\n

Solución: Cambie a la cabecera Authorization: Bearer (sin límite de\nfrecuencia).

\n

Consulte Límites de frecuencia.

\n

¿Cómo listo todos los endpoints?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

¿Cómo encuentro el endpoint correcto?

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

¿Puedo usar GET en lugar de POST?

\n

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

\n\n

Consulte GET /endpoints para ver las variantes GET disponibles.

\n

¿Cómo manejo los errores?

\n

Todos los errores devuelven JSON:

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

Consulte Errores y manejo de errores.

\n

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

\n

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

\n

¿La API admite CORS?

\n

Sí. Todos los endpoints devuelven:

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

¿Hay un SDK?

\n

Sí:

\n\n

Consulte Resumen de la API para más detalles.

\n

¿Cómo pagino?

\n

Use ?limit= y ?offset=:

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

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

\n

¿Puedo filtrar memorias por categoría o etiqueta?

\n

Sí:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

¿Cómo busco memorias?

\n

De dos formas:

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

Consulte Búsqueda FTS5 y Búsqueda semántica.

\n

¿Cómo actualizo una memoria?

\n

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

\n
# Initial store\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

¿Cómo elimino una memoria?

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

¿Puedo eliminar en lote?

\n

Sí:

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

Próximos pasos

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}