# Variables API

La Variables API è un key-value store veloce per stato effimero. A differenza
delle memorie (che sono indicizzate, ricercabili e strutturate), le variabili
sono ottimizzate per accesso rapido in lettura/scrittura — perfette per
contatori, flag e stato di sessione.

## Endpoint

### POST /var

Imposta o aggiorna una variabile.

```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

Ottiene una singola variabile.

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

Risposta:

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

### GET /var

Elenca tutte le variabili.

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

### DELETE /var/:key

Elimina una variabile.

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

## Quando usare le variabili rispetto alla memoria

| Caso d'uso | Usi |
|----------|-----|
| Nome utente, preferenze | Memoria (ricercabile, strutturata) |
| Timestamp ultima sessione | Variabile (stato effimero) |
| Contatore (es. messaggi inviati) | Variabile (aggiornamenti frequenti) |
| Stato workflow ("passo 3 di 5 fatto") | Variabile (transiente) |
| Note di progetto lunghe | Memoria (indicizzata full-text) |
| Script riutilizzabili | Script store (nominati, versionati) |

## Modelli comuni

### Traccia l'ultima sessione

```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)
```

### Modello contatore

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

### Feature flag

```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
```

## Prossimi passi

- [Memory API](/docs/api/memory) — per dati strutturati e ricercabili
- [Cron & Scheduler](/docs/api/cron)