{"title":"Resumen de la API y URL base","slug":"overview","category":"api","summary":"Todos los endpoints de la API de Synapse, URL base, patrones de autenticación y formatos de respuesta de un vistazo.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":602,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Resumen de la API y URL base\n\nLa API de Synapse es una API HTTP RESTful. Todos los endpoints devuelven JSON\n(excepto donde se indique lo contrario). Esta página cubre lo esencial que debe\nconocer antes de profundizar en endpoints específicos.\n\n## URL base\n\n```\nhttps://synapse.schaefer.zone\n```\n\nTodas las rutas de esta documentación son relativas a esta URL base. Para\ninstancias autoalojadas, sustitúyala por su propia URL.\n\n## Autenticación\n\nExisten dos métodos, ambos enviados mediante la cabecera `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # para endpoints de datos\nAuthorization: Bearer YOUR_JWT # para endpoints de cuenta\n```\n\nO mediante el parámetro de consulta (limitado a 60/min):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nConsulte [Autenticación](/docs/getting-started/authentication) para más detalles.\n\n## Grupos de endpoints\n\n| Grupo | Auth | Descripción |\n|-------|------|-------------|\n| Public | Ninguna | Página de inicio, health, OpenAPI, docs |\n| Memory | Mind Key | CRUD, búsqueda, sincronización, embeddings |\n| Chat | Mind Key / JWT | Mensajería asíncrona entre humano y agente |\n| Tasks | Mind Key | Gestión de tareas |\n| Scripts | Mind Key / JWT | Almacén persistente de scripts |\n| Scheduler | Mind Key | Trabajos cron + variables |\n| Webhooks | Mind Key | Callbacks HTTP ante eventos |\n| Computers | Mind Key / JWT | Control remoto de computadoras |\n| User/Minds | JWT | Cuenta + gestión de minds |\n| Sharing | JWT | Compartir minds entre usuarios |\n| Push | JWT | Suscripciones Web Push |\n| Tools | Ninguna | Hora, calculadora, aleatorios (utilidades públicas) |\n\n## Formatos de respuesta\n\n- **JSON** (predeterminado): `{ \"key\": \"value\", ... }`\n- **Texto plano**: `/memory/recall` devuelve texto optimizado para LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Envoltorio estándar de respuesta\n\nLas respuestas exitosas devuelven los datos directamente:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nLas respuestas de error usan este formato:\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\n> [!NOTE]\n> El campo `docs` enlaza a la documentación relevante para errores comunes.\n\n## Códigos de estado HTTP\n\n| Código | Significado |\n|------|---------|\n| 200 | Éxito (GET, PUT) |\n| 201 | Creado (POST) |\n| 204 | Sin contenido (DELETE) |\n| 400 | Solicitud incorrecta (error de validación) |\n| 401 | No autorizado (token ausente/inválido) |\n| 403 | Prohibido (tipo de token incorrecto) |\n| 404 | No encontrado (la ruta no existe) |\n| 409 | Conflicto (duplicado) |\n| 429 | Demasiadas solicitudes (límite de frecuencia) |\n| 500 | Error del servidor |\n\n## Endpoints de descubrimiento\n\n| Endpoint | Propósito |\n|----------|---------|\n| `GET /` | Página de inicio (optimizada para LLM) |\n| `GET /endpoints` | Lista legible por máquina de todos los endpoints |\n| `GET /endpoints?format=text` | Lista de endpoints en texto plano |\n| `GET /openapi.json` | Especificación OpenAPI 3.0 |\n| `GET /help` | Documentación completa de la API (HTML) |\n| `GET /help?format=json` | Documentación de la API en JSON |\n| `GET /docs` | Sistema de documentación (HTML) |\n| `GET /docs?format=json` | Índice de documentación (JSON) |\n| `GET /docs?format=text&scope=all` | Toda la documentación en un bloque de texto |\n| `GET /playground` | Playground interactivo de la API |\n\n## Límites de frecuencia\n\n| Método de auth | Límite |\n|-------------|-------|\n| Mind Key (cabecera) | Ninguno |\n| Mind Key (?key=) | 60/min por IP |\n| JWT (cabecera) | Ninguno |\n| Endpoints públicos | Ninguno |\n\nLas respuestas con límite de frecuencia incluyen:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Paginación\n\nLos endpoints de lista admiten `?limit=` y `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nLímite predeterminado: 100. Límite máximo: 500.\n\n## CORS\n\nTodos los endpoints admiten CORS para clientes basados en navegador:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDKs y clientes\n\n- **SDK Node.js**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **Servidor MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **Cliente HTTP**: cualquier librería HTTP (curl, fetch, axios, etc.)\n\n## Próximos pasos\n\n- [API de Memory](/docs/api/memory) — los endpoints más importantes\n- [API de Chat](/docs/api/chat) — comunicación asíncrona humano-agente\n- [Errores y manejo de errores](/docs/api/errors)\n","content_html":"

Resumen de la API y URL base

\n

La API de Synapse es una API HTTP RESTful. Todos los endpoints devuelven JSON\n(excepto donde se indique lo contrario). Esta página cubre lo esencial que debe\nconocer antes de profundizar en endpoints específicos.

\n

URL base

\n
https://synapse.schaefer.zone

Todas las rutas de esta documentación son relativas a esta URL base. Para\ninstancias autoalojadas, sustitúyala por su propia URL.

\n

Autenticación

\n

Existen dos métodos, ambos enviados mediante la cabecera Authorization:

\n
Authorization: Bearer YOUR_MIND_KEY    # para endpoints de datos\nAuthorization: Bearer YOUR_JWT          # para endpoints de cuenta

O mediante el parámetro de consulta (limitado a 60/min):

\n
?key=YOUR_MIND_KEY

Consulte Autenticación para más detalles.

\n

Grupos de endpoints

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GrupoAuthDescripción
PublicNingunaPágina de inicio, health, OpenAPI, docs
MemoryMind KeyCRUD, búsqueda, sincronización, embeddings
ChatMind Key / JWTMensajería asíncrona entre humano y agente
TasksMind KeyGestión de tareas
ScriptsMind Key / JWTAlmacén persistente de scripts
SchedulerMind KeyTrabajos cron + variables
WebhooksMind KeyCallbacks HTTP ante eventos
ComputersMind Key / JWTControl remoto de computadoras
User/MindsJWTCuenta + gestión de minds
SharingJWTCompartir minds entre usuarios
PushJWTSuscripciones Web Push
ToolsNingunaHora, calculadora, aleatorios (utilidades públicas)
\n

Formatos de respuesta

\n\n

Envoltorio estándar de respuesta

\n

Las respuestas exitosas devuelven los datos directamente:

\n
{ "id": "mem_001", "status": "stored" }

Las respuestas de error usan este formato:

\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}
El campo `docs` enlaza a la documentación relevante para errores comunes.

Códigos de estado HTTP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CódigoSignificado
200Éxito (GET, PUT)
201Creado (POST)
204Sin contenido (DELETE)
400Solicitud incorrecta (error de validación)
401No autorizado (token ausente/inválido)
403Prohibido (tipo de token incorrecto)
404No encontrado (la ruta no existe)
409Conflicto (duplicado)
429Demasiadas solicitudes (límite de frecuencia)
500Error del servidor
\n

Endpoints de descubrimiento

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPropósito
GET /Página de inicio (optimizada para LLM)
GET /endpointsLista legible por máquina de todos los endpoints
GET /endpoints?format=textLista de endpoints en texto plano
GET /openapi.jsonEspecificación OpenAPI 3.0
GET /helpDocumentación completa de la API (HTML)
GET /help?format=jsonDocumentación de la API en JSON
GET /docsSistema de documentación (HTML)
GET /docs?format=jsonÍndice de documentación (JSON)
GET /docs?format=text&scope=allToda la documentación en un bloque de texto
GET /playgroundPlayground interactivo de la API
\n

Límites de frecuencia

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Método de authLímite
Mind Key (cabecera)Ninguno
Mind Key (?key=)60/min por IP
JWT (cabecera)Ninguno
Endpoints públicosNinguno
\n

Las respuestas con límite de frecuencia incluyen:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Paginación

\n

Los endpoints de lista admiten ?limit= y ?offset=:

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

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

\n

CORS

\n

Todos los endpoints admiten CORS para clientes basados en navegador:

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

SDKs y clientes

\n\n

Próximos pasos

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