# Resumen de la API y URL base

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

## URL base

```
https://synapse.schaefer.zone
```

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

## Autenticación

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

```
Authorization: Bearer YOUR_MIND_KEY    # para endpoints de datos
Authorization: Bearer YOUR_JWT          # para endpoints de cuenta
```

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

```
?key=YOUR_MIND_KEY
```

Consulte [Autenticación](/docs/getting-started/authentication) para más detalles.

## Grupos de endpoints

| Grupo | Auth | Descripción |
|-------|------|-------------|
| Public | Ninguna | Página de inicio, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, búsqueda, sincronización, embeddings |
| Chat | Mind Key / JWT | Mensajería asíncrona entre humano y agente |
| Tasks | Mind Key | Gestión de tareas |
| Scripts | Mind Key / JWT | Almacén persistente de scripts |
| Scheduler | Mind Key | Trabajos cron + variables |
| Webhooks | Mind Key | Callbacks HTTP ante eventos |
| Computers | Mind Key / JWT | Control remoto de computadoras |
| User/Minds | JWT | Cuenta + gestión de minds |
| Sharing | JWT | Compartir minds entre usuarios |
| Push | JWT | Suscripciones Web Push |
| Tools | Ninguna | Hora, calculadora, aleatorios (utilidades públicas) |

## Formatos de respuesta

- **JSON** (predeterminado): `{ "key": "value", ... }`
- **Texto plano**: `/memory/recall` devuelve texto optimizado para LLM
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Envoltorio estándar de respuesta

Las respuestas exitosas devuelven los datos directamente:

```json
{ "id": "mem_001", "status": "stored" }
```

Las respuestas de error usan este formato:

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

> [!NOTE]
> El campo `docs` enlaza a la documentación relevante para errores comunes.

## Códigos de estado HTTP

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

## Endpoints de descubrimiento

| Endpoint | Propósito |
|----------|---------|
| `GET /` | Página de inicio (optimizada para LLM) |
| `GET /endpoints` | Lista legible por máquina de todos los endpoints |
| `GET /endpoints?format=text` | Lista de endpoints en texto plano |
| `GET /openapi.json` | Especificación OpenAPI 3.0 |
| `GET /help` | Documentación completa de la API (HTML) |
| `GET /help?format=json` | Documentación de la API en JSON |
| `GET /docs` | Sistema de documentación (HTML) |
| `GET /docs?format=json` | Índice de documentación (JSON) |
| `GET /docs?format=text&scope=all` | Toda la documentación en un bloque de texto |
| `GET /playground` | Playground interactivo de la API |

## Límites de frecuencia

| Método de auth | Límite |
|-------------|-------|
| Mind Key (cabecera) | Ninguno |
| Mind Key (?key=) | 60/min por IP |
| JWT (cabecera) | Ninguno |
| Endpoints públicos | Ninguno |

Las respuestas con límite de frecuencia incluyen:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)
```

## Paginación

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

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

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

## CORS

Todos los endpoints admiten CORS para clientes basados en navegador:

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

## SDKs y clientes

- **SDK Node.js**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **Servidor MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **Cliente HTTP**: cualquier librería HTTP (curl, fetch, axios, etc.)

## Próximos pasos

- [API de Memory](/docs/api/memory) — los endpoints más importantes
- [API de Chat](/docs/api/chat) — comunicación asíncrona humano-agente
- [Errores y manejo de errores](/docs/api/errors)