# API de Variables

La API de Variables es un almacén rápido clave-valor para estado efímero. A
diferencia de las memorias (que están indexadas, son buscables y estructuradas),
las variables están optimizadas para acceso rápido de lectura/escritura —
perfectas para contadores, flags y estado de sesión.

## Endpoints

### POST /var

Establece o actualiza una variable.

```bash
curl -X POST https://synapse.schaefer.zone/var \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "last_session_at", "value": "2026-06-27T14:00:00Z"}'
```

### GET /var/:key

Obtiene una variable individual.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

Respuesta:

```json
{ "key": "last_session_at", "value": "2026-06-27T14:00:00Z", "updated_at": "..." }
```

### GET /var

Lista todas las variables.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var
```

### DELETE /var/:key

Elimina una variable.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

## Cuándo usar Variables vs Memory

| Caso de uso | Usar |
|----------|-----|
| Nombre, preferencias | Memory (buscable, estructurado) |
| Timestamp de última sesión | Variable (estado efímero) |
| Contador (p. ej. mensajes enviados) | Variable (actualizaciones frecuentes) |
| Estado de workflow ("paso 3 de 5 completado") | Variable (transitorio) |
| Notas largas de proyecto | Memory (indexado de texto completo) |
| Scripts reutilizables | Script store (con nombre, versionado) |

## Patrones comunes

### Seguimiento de la última sesión

```bash
# At session end
curl -X POST .../var -d '{"key": "last_session_at", "value": "'$(date -Iseconds)'"}'

# At session start
LAST=$(curl .../var/last_session_at | jq -r .value)
curl .../memory/diff?since=$(date -d "$LAST" +%s)
```

### Patrón contador

```bash
# Increment
N=$(curl .../var/api_calls | jq -r .value)
curl -X POST .../var -d "{\"key\": \"api_calls\", \"value\": $((N+1))}"
```

### Feature flags

```bash
curl -X POST .../var -d '{"key": "feature_x_enabled", "value": "true"}'

# Check
ENABLED=$(curl .../var/feature_x_enabled | jq -r .value)
if [ "$ENABLED" = "true" ]; then ... fi
```

## Próximos pasos

- [API de Memory](/docs/api/memory) — para datos estructurados y buscables
- [Cron y Scheduler](/docs/api/cron)