# API de Variáveis

A API de Variáveis é um armazenamento key-value rápido para estado efêmero.
Diferente das memórias (que são indexadas, pesquisáveis e estruturadas), as
variáveis são otimizadas para acesso rápido de leitura/escrita — perfeitas para
contadores, flags e estado de sessão.

## Endpoints

### POST /var

Define ou atualiza uma variável.

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

Obtém uma única variável.

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

Resposta:

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

### GET /var

Lista todas as variáveis.

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

### DELETE /var/:key

Exclui uma variável.

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

## Quando usar Variáveis vs Memória

| Caso de uso | Use |
|-------------|-----|
| Nome do usuário, preferências | Memória (pesquisável, estruturada) |
| Timestamp da última sessão | Variável (estado efêmero) |
| Contador (ex.: mensagens enviadas) | Variável (atualizações frequentes) |
| Estado de workflow ("passo 3 de 5 concluído") | Variável (transitório) |
| Notas longas de projeto | Memória (indexada em texto completo) |
| Scripts reutilizáveis | Armazenamento de scripts (nomeados, versionados) |

## Padrões comuns

### Rastrear última sessão

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

### Padrão de 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 passos

- [API de Memória](/docs/api/memory) — para dados estruturados e pesquisáveis
- [Cron & Agendador](/docs/api/cron)